理解REST:动词、错误代码和身份验证

我正在寻找一种方法来包装api的默认功能在我的基于php的web应用程序，数据库和cms。

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

我最喜欢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. 我需要更多的动词

创建、更新和删除在理论上可能已经足够了，但实际上我需要更多的动词。我知道这些东西可以嵌入到更新请求中，但它们是特定的操作，可以有特定的返回代码，我不想把它们都扔到一个操作中。

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

activate_login
deactivate_login
change_password
add_credit

我该如何表达像RESTful URL体系结构那样的动作呢?

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

/api/users/1/activate_login

并等待状态码返回。

但是，这偏离了使用HTTP谓词的想法。你怎么看?

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

A great part of REST's beauty stems from its use of standard HTTP methods. On an error, I emit a header with a 3xx,4xx or 5xx error status code. For a detailed error description, I can use the body (right?). So far so good. But what would be the way to transmit a proprietary error code that is more detailed in describing what went wrong (e.g. "failed to connect to database", or "database login wrong")? If I put it into the body along with the message, I have to parse it out afterwards. Is there a standard header for this kind of thing?

4. 如何进行身份验证

遵循REST原则的基于API密钥的身份验证是什么样子的? 除了公然违反REST原则之外，在验证REST客户机时使用会话是否有强烈的反对之处?:)(这里只是半开玩笑，基于会话的身份验证在我现有的基础设施中可以很好地发挥作用。)

当前回答

其他基本知识

REST有一个统一的接口约束，它规定REST客户端必须依赖于标准，而不是实际REST服务的特定于应用程序的细节，因此REST客户端不会因微小的更改而中断，而且可能是可重用的。

因此，REST客户机和REST服务之间存在一个契约。如果您使用HTTP作为底层协议，那么以下标准是合同的一部分:

HTTP 1.1 method definitions status code definitions cache control headers accept and content-type headers auth headers IRI (utf8 URI) body (pick one) registered application specific MIME type, e.g. maze+xml vendor specific MIME type, e.g. vnd.github+json generic MIME type with application specific RDF vocab, e.g. ld+json & hydra, schema.org application specific profile, e.g. hal+json & profile link param (I guess) hyperlinks what should contain them (pick one) sending in link headers sending in a hypermedia response, e.g. html, atom+xml, hal+json, ld+json&hydra, etc... semantics use IANA link relations and probably custom link relations use an application specific RDF vocab

REST有一个无状态约束，它声明REST服务和客户机之间的通信必须是无状态的。这意味着REST服务不能维护客户端状态，因此您不能拥有服务器端会话存储。你必须验证每一个请求。例如，HTTP基本认证(HTTP标准的一部分)是可以的，因为它会在每个请求中发送用户名和密码。

来回答你的问题

是的，它可以是。

值得一提的是，客户端并不关心IRI结构，他们关心的是语义，因为他们遵循具有链接关系或链接数据(RDF)属性的链接。

关于IRI唯一重要的一点是，单个IRI必须只能标识单个资源。允许单个资源(如用户)拥有许多不同的IRIs。

我们使用/users/123/password这样漂亮的IRIs的原因很简单;当你通过阅读IRI来理解它时，在服务器上编写路由逻辑就容易得多了。

你有更多的动词，如PUT, PATCH, OPTIONS，甚至更多，但你不需要更多…而不是添加新的动词，你必须学习如何添加新的资源。

   deactivate_login -> PUT /login/active false
   change_password -> PUT /user/xy/password "newpass"
   add_credit -> POST /credit/raise {details: {}}

(由于无状态约束，从REST的角度来看，登录没有意义。)

您的用户并不关心问题存在的原因。他们只想知道是否有成功或错误，可能是他们能理解的错误消息，例如:“对不起，但我们不能保存您的帖子。”等等……

HTTP状态标头是标准标头。其他的都应该在身体里。例如，单个报头不足以描述详细的多语言错误消息。

The stateless constraint (along with the cache and layered system constraints) ensures that the service scales well. You surely don't wan't to maintain millions of sessions on the server, when you can do the same on the clients... The 3rd party client gets an access token if the user grants access to it using the main client. After that the 3rd party client sends the access token with every request. There are more complicated solutions, for example you can sign every single request, etc. For further details check the OAuth manual.

相关文献

架构风格与基于网络的软件架构设计 Roy Thomas Fielding博士论文(REST作者) 2000年，加州大学欧文分校第三代Web api——弥合REST和关联数据之间的差距 Markus Lanthaler博士论文(JSON-LD合著者，Hydra作者) 2014年，奥地利格拉茨理工大学

2014-09-17 22:24:33

其他回答

我建议(作为第一步)PUT应该只用于更新现有实体。POST应该用于创建新的。即。

/api/users     when called with PUT, creates user record

我觉得不对劲。然而，第一部分的其余部分(重新使用动词)看起来是合乎逻辑的。

2010-01-04 20:03:06

使用post当你不知道如何新的资源URI看起来像(你创建新用户，应用程序将分配新用户它的id)， PUT更新或创建资源，你知道他们将如何表示(示例:PUT /myfiles/thisismynewfile.txt) 在消息正文中返回错误描述您可以使用HTTP身份验证(如果足够的话) Web服务应该是状态

2010-01-04 20:06:15

关于REST返回码:将HTTP协议代码和REST结果混淆是错误的。

然而，我看到许多实现混合了它们，许多开发人员可能不同意我的观点。

HTTP返回码与HTTP请求本身相关。REST调用是使用超文本传输协议(Hypertext Transfer Protocol)请求完成的，它的工作级别比调用的REST方法本身要低。REST是一种概念/方法，其输出是业务/逻辑结果，而HTTP结果代码是传输结果。

例如，当你调用/users/时返回“404 Not found”是令人困惑的，因为它可能意味着:

URI错误(HTTP) 没有找到用户(REST)

“403禁止/拒绝访问”可能是指:

需要特别许可。浏览器可以通过询问用户/密码来处理它。(HTTP) 服务器上配置的访问权限错误。(HTTP) 您需要进行身份验证(REST)

这个列表可能会继续出现“500服务器错误”(Apache/Nginx HTTP抛出错误或REST中的业务约束错误)或其他HTTP错误等……

从代码中，很难理解失败的原因是什么，HTTP(传输)失败还是REST(逻辑)失败。

如果HTTP请求物理上被成功执行，它应该总是返回200个代码，不管是否找到记录。因为URI资源是被http服务器找到并处理的。是的，它可能返回一个空集。是否有可能收到一个空网页200作为http结果，对吗?

相反，你可以返回200个HTTP代码和一个带有空数组/对象的JSON，或者使用bool result/success标志来通知所执行的操作状态。

此外，一些互联网提供商可能会拦截您的请求并返回404 http代码。这并不意味着您的数据找不到，而是在传输级别上出了问题。

从维基:

In July 2004, the UK telecom provider BT Group deployed the Cleanfeed content blocking system, which returns a 404 error to any request for content identified as potentially illegal by the Internet Watch Foundation. Other ISPs return a HTTP 403 "forbidden" error in the same circumstances. The practice of employing fake 404 errors as a means to conceal censorship has also been reported in Thailand and Tunisia. In Tunisia, where censorship was severe before the 2011 revolution, people became aware of the nature of the fake 404 errors and created an imaginary character named "Ammar 404" who represents "the invisible censor".

2017-09-23 12:08:47