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

问题:

只使用 GET 和 POST 可以吗？

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

保持这些资源版本化的好方法是什么？在我的示例中，我在域名后使用/1/来表示版本 1。替代方案是:http://api1.domain.com ... 或 http://api-1.domain.com ... 或 http://apiv1.domain.com ... 或 http://api-v1.domain.com ... 或 http://api.domain.com/v1/ ... 或

验证的最佳方法是什么？

Answer 1

在深入研究 REST 之前，您确实需要掌握以下术语:

Resource - The things/data you want to make available in your API (in your case a "User")

URI - A universally unique ID for a resource. Should mention nothing about the method being performed (e.g. shouldn't contain "add" or "delete"). The structure of your URI however doesn't make your app any more or less RESTful - this is a common misconception.

Uniform Interface - A fixed set of operations you can perform on your resources, in most cases this is HTTP. There are clear definitions for the purpose of each of these HTTP methods.

你现在的 URI 最令人不安的是，它们有关于正在执行的操作的信息。 URI 是 ID，仅此而已!
让我们举一个现实世界的例子。我的名字是内森。 “Nathan”可以被认为是我的 ID(或者用 URI 来表示——为了这个示例的目的，假设我是唯一的“Nathan”)。我的姓名/ID 不会因您希望与我互动的方式而改变，例如当你想和我打招呼时，我的名字不会变成“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>

至于你的问题:

在适当的时候使用 PUT 和 DELETE 并避免重载 POST 来处理这些函数，因为它会破坏 HTTP's definition of POST . HTTP 是您的统一接口(interface)。这是您与 API 用户之间关于他们如何期望与您的服务交互的契约(Contract)。如果你破坏了 HTTP，你就破坏了这个契约(Contract)。

完全删除“添加”。使用 HTTP 的 Content-Type header 来指定发布数据的 MIME 类型。

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

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