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

Question

我正准备在我自己的服务器上使用PHP为我的部门的其他程序员提供Web服务.

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

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

数据以各种格式返回,xml,json,jsonp等.

通话示例:/？offices = ABC | XYZ&format = xml

首先,我想知道我是否正确将我的服务称为"API"？

另外,我也想知道如何最好地处理失败.

如果用户没有提交预期的输入,我会直接发送短信 - "您没有提交任何办公室".

在任何其他无法预料的故障的情况下,它在所选格式的有效载荷中返回失败消息,例如json,其中单个阵列"失败"并且我已经记录了这一点.

最近在REST上阅读了一些内容,当失败不是由于滥用"API"引起的 - 我应该返回HTTP代码200之外的其他内容吗？

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

我应该制作另一个GET选项吗？

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

或者我在API和REST之间混淆了什么？

SO建议这篇文章涉及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状态代码.

DELETE/api/users/example - 删除现有用户帐户.可以根据结果返回各种HTTP状态代码.

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

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

希望这些信息有用,而不是过载.:-)