公共API设计-使用http代码处理失败？ 那是REST吗？

Question

我将要在自己的服务器上使用PHP为我所在领域的其他程序员提供Web服务。

因为这是我第一次这样做，所以我首先研究了我经常使用的API，Flickr等。

通过检查GET参数，我的服务返回从很大的csv文件中提取的精细数据，它是只读的。

数据以各种格式返回，例如xml，json，jsonp等。

呼叫示例：/？offices = ABC | XYZ＆format = xml

首先，我想知道我是否正确地将我的服务称为“ API”？

我也想知道如何最好地处理失败。

如果用户未提交预期的输入，我将返回纯文本消息-“您未提交任何办公室”。

在发生任何其他无法预料的故障时，此刻它会以所选格式的有效负载返回一条故障消息，例如，其中包含单个数组“ fail”的json，我已对此进行了记录。

最近在REST上进行了一些阅读，如果不是由于滥用“ API”而导致的失败-我是否应该返回HTTP代码200以外的内容？

如果您正在访问此服务，您希望看到什么？

我应该把它作为另一个GET选项吗？

例如/？offices = ABC | XYZ＆format = xml＆on_failure = http

还是我在术语API和REST之间感到困惑？

所以建议这个帖子，涉及400/401

REST API服务针对验证失败返回什么适当的HTTP状态代码？

但我想澄清我使用的术语。 如果有效负载包含错误消息-就像Flickr一样，那么为什么我应该远离它呢？

Answer 1

像Flickr和Twitter这样的大型提供者已经使REST的定义更加混乱。 现在，许多开发人员错误地认为基于HTTP的任何服务或API都是“ RESTful”的。 您在此处描述的更多是使用RPC形式的数据Web服务。 真正的RESTful API使用流畅的HTTP和Web标准，并且以资源为中心。

为了回答有关HTTP状态代码的主要问题，我想说对于RPC服务来说没有必要，因为HTTP状态代码并不总是直接转换为方法调用错误。 更好的方法是映射您自己的错误代码，并将其与状态消息一起返回。

例如，用于用户查找的RPC服务在成功时可能返回以下内容：

SUCCESS=1
USERNAME=example
FIRSTNAME=Example
LASTNAME=User
DISPLAYNAME=Example User

相同的服务可能会在失败时返回以下内容：

SUCCESS=0
ERRORCODE=1002
ERRORMSG=User subsystem error; requested user was not found.

在RPC服务中，响应的确切细节非常灵活。 它所做的只是将方法调用的结果中继给调用者。 只要记录下开发人员应该看到的内容，并返回清晰一致的消息，就可以正常工作。 RPC服务应返回的唯一HTTP状态代码是200和500（只有这样，当事情严重中断时，您甚至无法返回正确的错误）。

回到REST的问题，如果我们将用户视为资源并使用适当的URL方案，则可以使同一用户服务成为RESTful。 RESTful API的非常非常基本的组成如下：

GET / api / users-应该返回系统中可用用户帐户的列表。

GET / api / users / example-应该返回示例帐户的详细信息； 如果用户不存在，则返回404 HTTP状态。

POST / api / users-创建一个新的用户帐户； 应该返回到新创建的帐户的链接（这样做的方式有所不同，但是LOCATION标头在这里有意义）。 根据结果​​，可能会返回各种HTTP状态代码。

PUT / api / users / example-编辑现有用户帐户的详细信息。 根据结果​​，可能会返回各种HTTP状态代码。

删除/ api / users / example-删除现有的用户帐户。 根据结果​​，可能会返回各种HTTP状态代码。

RESTful接口最常用的标准HTTP状态代码如下。

• 200 OK-请求已成功完成。 如果此请求创建了可通过URI寻址的新资源，并且返回了包含新资源表示形式的响应主体，则将返回200状态，并带有Location标头，其中包含新创建资源的规范URI。
• 201已创建 -创建新资源的请求已完成，并且没有返回包含新资源表示形式的响应正文。 还应该返回一个位置标头，其中包含新创建资源的规范URI。
• 202 Accepted-请求已被接受进行处理，但处理尚未完成。 根据HTTP / 1.1规范，返回的实体（如果有的话）应该包括请求当前状态的指示，以及指向状态监视器的指针或用户何时可以期望完成请求的一些估计。
• 204 No Content-服务器已完成请求，但不需要返回响应消息正文。
• 400错误的请求 -无法处理该请求，因为该请求包含丢失或无效的信息（例如输入字段上的验证错误，缺少的必需值等）。
• 401未经授权 -此请求中包含的身份验证凭据丢失或无效。
• 403禁止访问 -服务器识别了您的凭据，但是您不具有执行此请求的权限。
• 找不到404-请求指定了不存在的资源的URI。
• 405不允许的方法 -此请求URI不支持在请求中指定的HTTP动词（DELETE，GET，HEAD，POST，PUT）。
• 406不可接受 -此请求标识的资源无法生成与请求的“接受”标头中的媒体类型之一相对应的表示形式。
• 409冲突 -创建或更新请求无法完成，因为它会导致服务器支持的资源的当前状态发生冲突（例如，尝试使用已经分配给某些现有标识符的唯一标识符来创建新资源资源）。
• 500 Internal Server Error-服务器遇到意外状况，阻止其满足请求。
• 501未实现 -服务器不（当前）不支持满足请求所需的功能。
• 503服务不可用 -由于暂时的服务器过载或维护，服务器当前无法处理该请求。

希望此信息有用，而不是过载。 :-)