2

我正在尝试开发一个简单的 REST API。我仍在尝试了解它的基本架构范式。我需要以下帮助：

  1. “资源”应该是名词吧？所以，我应该有“用户”，而不是“getUser”，对吧？

  2. 我在一些 API 中看到过这种方法：www.domain.com/users/（返回列表）、www.domain.com/users/user（针对用户执行某些操作）。这种方法好吗？

  3. 在我见过的大多数示例中，输入和输出值通常只是名称/值对（例如 color='red'）。如果我想发送或返回比这更复杂的东西怎么办？我是否被迫只处理 XML？

  4. 假设使用 PUT to /user/ 方法将新用户添加到系统。什么是输入参数的好格式（假设唯一需要的字段是“用户名”和“密码”）？如果用户成功，什么是好的响应？如果用户失败（并且我想返回描述性错误消息）怎么办？

  5. 什么是身份验证和授权的好且简单的方法？我想将大多数方法限制为成功“登录”的用户。每次通话时都传递用户名/密码可以吗？传递一个被认为更安全的令牌（如果是，应该如何在到期等方面实现）？

4

2 回答 2

9

对于第 1 点，是的。名词是预期的。

对于第 2 点，我希望/users给我一个用户列表。我希望/users/123给我一个特定的用户。

对于第 3 点，您可以返回任何内容。您的客户可以指定它想要什么。例如text/xml，application/json等等，通过使用 HTTP 请求标头，并且您应该尽可能地遵守该请求（尽管您可能只处理，例如text/xml- 这在很多情况下都是合理的）。

对于第 4 点，我希望POST创建一个新用户。PUT将更新现有对象。要报告成功或错误，您应该使用现有的 HTTP 成功/错误代码。例如200 OK。有关更多信息，请参阅此 SO 答案。

于 2010-02-14T14:30:51.400 回答
6

REST 最重要的约束是超媒体约束（“超文本作为应用程序状态的引擎”）。将您的 Web 应用程序视为一个状态机，其中每个状态都可以由客户端请求（例如 GET /user/1）。一旦客户端具有一个这样的状态（想想：用户正在查看网页），它就会看到一堆它可以跟随以进入应用程序中的下一个状态的链接。例如，可能存在来自“用户状态”的链接，客户端可以按照该链接进入详细信息状态。

这样，服务器在运行时一次向客户端呈现应用程序的状态机一个状态。聪明的事情是：由于状态机是在运行时发现的，因此服务器可以在运行时动态更改状态机。

话说回来...

1. 资源本质上代表您想要呈现给客户端的应用程序状态。这通常会与域对象（例如用户）紧密匹配，但请确保您了解为它们提供的表示不仅仅是序列化的域对象，而是您的 Web 应用程序的状态。

从 GET /users/123 的角度思考是可以的。不要在 URI 中放置任何操作。虽然没有害处（它只是一个不透明的字符串），但至少可以说是令人困惑的。

2. 正如布赖恩所说。您可能想看看 Atom Publishing Protocol RFC (5023)，因为它很好地解释了创建/读取/更新周期。

3. 关注面向文档的消息。媒体类型是 REST 的重要组成部分，因为它们（完全）提供了应用程序语义。不要使用诸如 application/xml 或 application/json 之类的泛型类型，因为您将围绕通常隐含的模式耦合您的客户端和服务器。如果没有什么能满足你的需求，那就自己编一个吧。

也许您对我使用 UBL 一起破解的示例感兴趣：http ://www.nordsc.com/blog/?cat=13

on 4. 通常，使用 POST /users/ 进行创建。看看 RFC 5023 - 这将澄清这一点。这是一个易于理解的规范。

5. 由于您不能使用会话（有状态服务器）并且是 RESTful 的，因此您必须在每个请求中发送凭据。各种 HTTP 身份验证方案已经处理了这个问题。这对于缓存也很重要，因为 HTTP Authorization 标头对缓存具有特殊的指定语义（没有公共缓存）。如果你把你的凭据塞进一个 cookie 中，你就会丢失那个重要的部分。

所有 HTTP 状态码都有一定的应用语义。使用它们，不要通过 HTTP 隧道传输您自己的错误语义。

您可以访问#rest IRC 或加入 Yahoo 上的 rest-discuss 进行详细讨论。

简

于 2010-02-14T15:00:10.700 回答