REST Web服务API设计

Question

只想获得有关我计划如何构建API的反馈.下面的虚拟方法.这是结构:

GET http://api.domain.com/1/users/ <-- returns a list of users
POST http://api.domain.com/1/users/add.xml <-- adds user
POST http://api.domain.com/1/users/update.xml <-- updates user
DELETE (or POST?) http://api.domain.com/1/users/delete.xml <-- deletes user

问题:

1. 可以使用GET和POST吗？
2. 我打算依靠文件名来指示要执行的操作(例如添加add.xml)是一个好主意吗？做这样的事情会更好:POST http://api.domain.com/1/users/add/data.xml？
3. 保持这些资源版本的好方法是什么？在我的示例中,我使用/ 1/after域名来表示版本1.替代方案将是:http://api1.domain.com ...或http://api-1.domain.com ...或者http://apiv1.domain.com ...或http://api-v1.domain.com ...或http://api.domain.com/v1/ ...或
4. 验证的最佳方法是什么？

Answer 1

在深入研究REST之前,您需要掌握以下几个术语:

资源 - 您希望在API中提供的内容/数据(在您的情况下为"用户")

URI - 资源的通用唯一ID .不应该提及正在执行的方法(例如,不应该包含"添加"或"删除").然而,您的URI结构不会使您的应用程序更多或更少RESTful - 这是一种常见的误解.

统一接口 - 您可以对资源执行的一组固定操作,在大多数情况下,这是HTTP.每种HTTP方法的目的都有明确的定义.

关于你的URI现在最不可思议的事情就是它们有关于正在执行的操作的信息.URI是ID,仅此而已!

让我们以现实世界为例.我的名字是内森."Nathan"可以被认为是我的ID(或者在宁静的术语URI中 - 出于本例的目的,假设我是唯一的"Nathan").根据您与我的互动方式,我的姓名/身份证不会改变,例如,当您想要问我时,我的名字不会改为"NathanSayHello".

REST也是如此.当您要更新该用户时,http://api.domain.com/users/1标识的用户不会更改为http://api.domain.com/users/1/update.xml.您正在使用的方法(例如PUT)隐含了您想要更新该用户的事实.

这是我对你的URI的建议

# Retrieve info about a user 
GET http://api.domain.com/user/<id>

# Retrieve set all users
GET http://api.domain.com/users

# Update the user IDed by api.domain.com/user/<id>
PUT http://api.domain.com/user/<id>

# Create a new user.  The details (even <id>) are based as the body of the request
POST http://api.domain.com/users

# Delete the user ID'd by api.domain.com/user/<id>
DELETE http://api.domain.com/user/<id>

至于你的问题:

1. 在适当的时候使用PUT和DELETE,并避免过载POST来处理这些函数,因为它破坏了HTTP的POST定义.HTTP是您的统一接口.这是您与API用户签订的有关他们如何与您的服务进行互动的合同.如果您违反HTTP,则会违反此合同.

2. 完全删除"添加".使用HTTP的Content-Type标头指定发布数据的mime类型.

3. 您是指API的版本还是资源的版本？ETag和其他响应头可用于对资源进行版本控制.

4. 这里有很多选择.基本HTTP身份验证(简单但不安全),摘要身份验证,自定义身份验证,如AWS.OAuth也是一种可能性.如果安全性至关重要,我使用客户端SSL证书.

Answer 2

1)你的设计可能不是.POST不是幂等的!因此,您不应该使用更新或删除,而是使用来自Rest的PUT和DELETE

2)更好的选择是在WS调用上使用标题Content-Type,例如:application/xml

3)同样在标题Content-Type上你可以使用它:application-v1.0/xml

4)不确定它是否是最好的,但可能最简单的方法是在RFC 2617中使用HTTP的内置身份验证机制.示例:AWS身份验证