Php 公共API设计-使用http代码处理故障？那是休息吗？

我正准备在我自己的服务器上使用PHP为我所在领域的程序员同事提供一个Web服务

由于这是我第一次这样做，我首先调查了我经常使用的API，Flickr等

我的服务通过检查GET参数返回从非常大的csv文件中提取的粒度数据，它是只读的

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

调用示例：/？offices=ABC | XYZ&format=xml

首先，我想知道我将我的服务定义为“API”是否正确

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

如果用户未提交预期输入，“您未能提交任何办公室”，我会直接返回文本消息

在任何其他不可预见的故障情况下，此时它以所选格式的有效负载返回故障消息，例如json，其中包含单个数组“fail”，我已经记录了这一点

最近读了一点REST，当故障不是由“API”的误用引起时，我应该返回HTTP代码200以外的内容吗

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

我应该让这成为另一个GET选项吗

e、 g/？offices=ABC | XYZ&format=xml&on|u failure=http

还是我在API和REST这两个术语之间搞混了

这篇文章是这样建议的，它涉及400/401

---

但我想澄清一下我使用的术语。如果有效负载包含错误消息——就像Flickr的情况一样，那么我为什么要偏离它呢？

像Flickr和Twitter这样的大型提供商已经把REST的定义搞得一团糟了。许多开发人员现在错误地认为HTTP上的任何服务或API都是“RESTful”的。真正的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-应返回 示例帐户的详细信息； 如果用户 不存在

POST/api/users-创建新用户 账户应返回指向 新创建的帐户（操作方式） 这会有所不同，但位置标头 在这里有意义）。各种HTTP状态 可能会返回代码，具体取决于 结果

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

删除/api/users/example-删除 现有用户帐户。各种HTTP 根据具体情况，可能会返回状态代码 关于结果

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

• 200正常-请求已成功完成。如果此请求创建了一个可使用URI寻址的新资源，并且返回了一个包含新资源表示的响应正文，则将返回一个200状态，其中位置头包含新创建资源的规范URI
• 201 Created-创建新资源的请求已完成，并且未返回包含新资源表示的响应正文。还应返回包含新创建资源的规范URI的位置头
• 202已接受-请求已接受处理，但处理尚未完成。根据HTTP/1.1规范，返回的实体（如果有的话）应该包括请求当前状态的指示，以及指向状态监视器的指针，或者用户可以预期何时完成请求的一些估计
• 204无内容-服务器完成了请求，但不需要返回响应消息正文
• 400错误请求-无法处理该请求，因为它包含丢失或无效的信息（例如输入字段上的验证错误、缺少必需值等）
• 401未经授权-此请求中包含的身份验证凭据丢失或无效
• 403禁止-服务器识别您的凭据，但您没有执行此请求的授权
• 404未找到-请求指定了不存在的资源的URI
• 405方法不允许-此请求URI不支持请求中指定的HTTP谓词（DELETE、GET、HEAD、POST、PUT）
• 406不可接受-此请求标识的资源无法生成对应于一个o的表示