REST Web服务API设计

只想获得有关我计划如何构建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

问题:

可以使用GET和POST吗？

我打算依靠文件名来指示要执行的操作(例如添加add.xml)是一个好主意吗？做这样的事情会更好:POST http://api.domain.com/1/users/add/data.xml？

保持这些资源版本的好方法是什么？在我的示例中,我使用/ 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/ ...或

验证的最佳方法是什么？

nategood.. 39

在深入研究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/

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

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

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

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

至于你的问题:

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

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

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

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

回复+1,但是:PUT/DELETE必须是幂等的,而不是POST.POST可以随心所欲."幂等"只意味着如果操作重复两次,它会产生相同的结果 - 在数学中说它是`f(f(x))= f(x)`.在我们的例子中,如果一个人对同一个资源做两个相同的PUT,结果必须与只做1的结果相同.另一方面,POST取决于开发人员给出的语义,可能会有不同的结果(例如,POST两次可能会发送2封电子邮件) (3认同)

---

Diego Dias.. 7

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

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

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

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

1> nategood..：

---

在深入研究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/

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

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

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

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

至于你的问题:

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

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

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

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

---

回复+1,但是:PUT/DELETE必须是幂等的,而不是POST.POST可以随心所欲."幂等"只意味着如果操作重复两次,它会产生相同的结果 - 在数学中说它是`f(f(x))= f(x)`.在我们的例子中,如果一个人对同一个资源做两个相同的PUT,结果必须与只做1的结果相同.另一方面,POST取决于开发人员给出的语义,可能会有不同的结果(例如,POST两次可能会发送2封电子邮件)

2> Diego Dias..：

---

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

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

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

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