web-services - 了解 REST : Verbs, 错误代码和身份验证

Question

我正在寻找一种方法来将 API 封装在基于 PHP 的 Web 应用程序、数据库和 CMS 中的默认函数中。

我环顾四周，发现了几个“骨架”框架。除了我的问题中的答案，还有Tonic ，我喜欢的 REST 框架，因为它非常轻量级。

我最喜欢 REST，因为它的简单性，并希望基于它创建一个 API 架构。我正在努力了解基本原则，但还没有完全理解它。因此，有一些问题。

1.我理解对了吗？

假设我有一个资源“用户”。我可以像这样设置一些 URI:

/api/users     when called with GET, lists users
/api/users     when called with POST, creates user record
/api/users/1   when called with GET, shows user record
               when called with PUT, updates user record
               when called with DELETE, deletes user record

到目前为止，这是 RESTful 架构的正确表示吗？

2.我需要更多动词

Create、Update 和 Delete 在理论上可能就足够了，但在实践中我将需要更多的动词。我意识到这些是可以嵌入到更新请求中的东西，但它们是具有特定返回码的特定操作，我不想将它们全部放入一个操作中。

在用户示例中想到的一些是:

activate_login
deactivate_login
change_password
add_credit

我将如何表达诸如 RESTful URL 架构中的操作？

我的直觉是对 URL 进行 GET 调用，例如

/api/users/1/activate_login 

并期待返回状态代码。

不过，这与使用 HTTP 动词的想法背道而驰。你怎么认为？

3.如何返回错误信息和代码

REST 的美妙之处很大一部分源于它使用标准 HTTP 方法。出现错误时，我会发出一个带有 3xx、4xx 或 5xx 错误状态代码的 header 。对于详细的错误描述，我可以使用正文(对吗？)。到现在为止还挺好。但是传输 的方式是什么？专有错误代码 更详细地描述出了什么问题(例如“无法连接到数据库”或“数据库登录错误”)？如果我把它和消息一起放到正文中，我必须在之后解析它。这种事情有标准标题吗？

4.如何做认证

遵循 REST 原则的基于 API key 的身份验证会是什么样子？

除了公然违反 REST 原则之外，在验证 REST 客户端时是否有反对使用 session 的优点？ :)(这里只是开个玩笑，基于 session 的身份验证可以很好地与我现有的基础架构配合使用。)

Answer 1

我注意到这个问题晚了几天，但我觉得我可以补充一些见解。我希望这对您的 RESTful 冒​​险有所帮助。

第 1 点:我理解正确吗？

你理解对了。这是 RESTful 架构的正确表示。您可以从 Wikipedia 中找到以下矩阵非常有助于定义您的名词和动词:

处理 时收藏 URI 像: http://example.com/resources/

获取 :列出集合的成员，并附上他们的成员 URI，以便进一步导航。例如，列出所有待售汽车。

放 :含义定义为“用另一个集合替换整个集合”。

发布 :在集合中创建一个新条目，其中 ID 由集合自动分配。创建的 ID 通常包含在此操作返回的数据中。

删除 :含义定义为“删除整个集合”。

处理 时成员(member) URI 像: http://example.com/resources/7HOU57Y

获取 : 检索以适当 MIME 类型表示的集合的寻址成员的表示。

放 :更新集合的寻址成员或使用指定的 ID 创建它。

发布 : 将被寻址的成员本身视为一个集合，并为其创建一个新的从属。

删除 : 删除集合的寻址成员。

第 2 点:我需要更多动词

一般来说，当您认为需要更多动词时，实际上可能意味着您的资源需要重新识别。请记住，在 REST 中，您始终对资源或资源集合进行操作。您选择的资源对于您的 API 定义非常重要。

激活/停用登录 :如果您正在创建一个新 session ，那么您可能需要将“ session ”视为资源。要创建新 session ，请使用 POST 到 http://example.com/sessions/与正文中的凭据。要使其过期，请使用 PUT 或 DELETE(可能取决于您是否打算保留 session 历史记录)到 http://example.com/sessions/SESSION_ID .

更改密码:这次资源是“用户”。你需要一个 PUT 到 http://example.com/users/USER_ID与正文中的旧密码和新密码。您正在处理“用户”资源，更改密码只是一个更新请求。它与关系数据库中的 UPDATE 语句非常相似。

My instinct would be to do a GET call to a URL like /api/users/1/activate_login

这违背了一个非常核心的 REST 原则:HTTP 动词的正确使用。任何 GET 请求都不应留下任何副作用。

例如，GET 请求永远不应该在数据库上创建 session 、返回带有新 session ID 的 cookie 或在服务器上留下任何残留物。 GET 动词就像数据库引擎中的 SELECT 语句。请记住，当使用相同的参数请求时，对任何带有 GET 动词的请求的响应都应该是可缓存的，就像请求静态网页时一样。

第 3 点:如何返回错误信息和代码

将 4xx 或 5xx HTTP 状态代码视为错误类别。您可以详细说明正文中的错误。

连接数据库失败:/ 数据库登录错误 :一般来说，对于这些类型的错误，您应该使用 500 错误。这是服务器端错误。客户没有做错任何事。 500 个错误通常被认为是“可重试的”。即客户端可以重试完全相同的请求，并期望一旦服务器的问题得到解决它会成功。在正文中指定细节，以便客户端能够为我们人类提供一些上下文。

另一类错误是 4xx 系列，这通常表明客户端做错了什么。特别是，此类错误通常会向客户端表明无需按原样重试请求，因为它将继续永久失败。即客户端需要在重试此请求之前更改某些内容。例如，“Resource not found”(HTTP 404)或“Malformed Request”(HTTP 400)错误就属于这一类。

第4点:如何做认证

正如第 1 点所指出的，您可能需要考虑创建一个 session ，而不是对用户进行身份验证。您将收到一个新的“ session ID”以及相应的 HTTP 状态代码(200:授予访问权限或 403:拒绝访问)。

然后你会问你的 RESTful 服务器:“你能给我这个 session ID 的资源吗？”。

没有经过身份验证的模式 - REST 是无状态的:您创建一个 session ，您要求服务器使用此 session ID 作为参数为您提供资源，并在注销时删除或过期 session 。