php – RESTful API中错误的最佳实践

在RESTful API中返回HTTP状态代码的最佳做法是什么？我正在使用Laravel 4作为我的 PHP框架.

在出现错误的情况下,应该使用

return Response::json('User Exists',401);

要么

包括成功的旗帜

return Response::json([
    'success' => false,'data' => 'User Exists'],401
);

要么

使用200而不是4xx,依靠成功来确定是否有错误

return Response::json([
    'success' => false,200
);

在成功的情况下,没有必要返回任何数据,你还会返回任何东西吗？

PHP API代码

public function getCheckUniqueEmail() {
    // Check if Email already exist in table 'users'
    $uniqueEmail = checkIfEmailExists();

    // Return JSON Response
    if($uniqueEmail) {
        // Validation fail (user exists)
        return Response::json('User Exists',401);
    } else {
        // Validation success
        // - Return anything?
    }
}

当你看着 list of available HTTP status codes时,你会在某种程度上意识到有很多,但是单独使用它们本身并不能真正解释一个错误.

所以要回答你的问题,有两个部分.一个是：您的API如何传达错误的原因,并添加API的用户(大多数情况下是另一个开发人员)可以阅读并采取行动的有用信息.您应该添加尽可能多的信息,包括机器可读性和可读性.

另一部分：HTTP状态代码如何帮助区分某些错误(和成功)状态？

后一部分实际上比一个人更难.有很多情况下,404被用来告诉“未找到”.而对于服务器端的任何错误都是500.

我不会使用状态401,除非我真的想允许操作成功,如果存在HTTP身份验证凭据. 401通常在浏览器中触发一个对话框,这是坏的.

如果资源来源是唯一的并且已经存在,状态“409冲突”似乎是适当的.如果创建用户成功,状态“201 Created”也听起来像个好主意.

请注意,有更多的状态代码,其中一些与HTTP协议(如DAV)的扩展有关,一些完全不标准(像Twitter API的状态“420增强您的冷静”).看看http://en.wikipedia.org/wiki/List_of_HTTP_status_codes,看看到目前为止已经使用了什么,并决定是否要使用适合你的错误情况的东西.

根据我的经验,很容易选择状态代码并使用它,但是很难按照现有的标准一致地执行.

不过,我不会因为其他人的抱怨而停在这里. :)正确的RESTful接口本身就是一项艰巨的任务,但存在的接口越多,收集的经验就越多.

编辑：

关于版本控制：把一个版本的标签放入网址是不好的做法,像这样：example.com/api/v1/stuff它会工作,但不是很好.

但首先是：你的客户如何指定他想要获得哪种表示,即他如何决定要获得JSON或XML？答案：使用Accept标题.他可以发送Accept：application / json for JSON和Accept：application / xml for XML.他甚至可以接受多种类型,而服务器可以决定要返回的内容.

除非服务器被设计为使用资源的多个表示(JSON或XML,客户端选择)来回答,否则客户端真的没有太多的选择.但是客户端至少发送“application / json”作为他唯一的选择仍然是一件好事,然后返回一个头部Content-type：application / json作为响应.这样一来,双方就会明确他们期望对方看到的内容.

现在为版本.如果您将版本放入网址,您可以有效地创建不同的资源(v1和v2),但实际上只有一个资源(= URL)具有不同的方法来访问它.当请求的参数和/或与当前版本不兼容的响应中的表示发生突然变化时,必须创建新版本的API.

因此,当您创建使用JSON的API时,不会处理通用JSON.你处理一个具体的JSON结构,这是你的API特有的.您可以并且可能应该在服务器发送的Content-type中指示. “供应商”扩展是这样的：内容类型：application / vnd.IAMVENDOR.MYAPI json将告诉世界基本数据结构是application / json,但它是您的公司和您的API真正地告诉哪个结构期望.而且这正是API请求的版本适用于：application / vnd.IAMVENDOR.MYAPI-v1 json.

因此,您不需要将该版本放在URL中,您希望客户端发送Accept：application / vnd.IAMVENDOR.MYAPI-v1 json标头,并以Content-type：application / vnd.IAMVENDOR.MYAPI-v1 json作为响应好.这真的改变了第一个版本,但是让我们看看当版本2发挥作用时,事情如何发展.

URL方法将创建一个完全无关的新资源.客户端会想知道example.com/api/v2/stuff是否与example.com/api/v1/stuff资源相同.客户端可能已经使用v1 API创建了一些资源,并且他存储了这些东西的URL.他应该如何将所有这些资源升级到v2？资源真的没有改变,他们是一样的,唯一改变的是它们在v2中看起来不一样.

是的,服务器可能会通过将重定向发送到v2 URL来通知客户端.但重定向并不表示客户端还必须升级客户端部分的API.

当使用带有该版本的accept标头时,资源的URL对于所有版本都是相同的.客户端决定使用版本1或2请求资源,并且服务器可能是如此友善,仍然以版本1响应来解答版本1请求,但是所有版本2请求都带有新的和闪亮的版本2响应.

如果服务器无法应答版本1请求,他可以通过发送HTTP状态“406不可接受”来通知客户端(所请求的资源只能根据请求中发送的Accept标头生成不能接受的内容).

客户端可以发送包含两个版本的accept标头,这使得服务器能够以最喜欢的方式进行响应,即,智能客户端可能会实现版本1和2,现在同时发送为接收头,并等待服务器升级从版本1到2.服务器将在每个响应中告诉它是否是版本1或2,并且客户端可以相应地采取行动 – 他不需要知道服务器版本升级的确切日期.

总结一下：对于一个非常基本的API,有限的,也许是内部的使用,即使有一个版本可能是过度的.但你永远不知道这是否会在一年之后成真.将版本号添加到API中总是一个很好的主意.而最好的一点是你的API即将使用的mime类型.检查单个现有版本应该是微不足道的,但是您可以选择稍后进行透明升级,而不会混淆现有客户端.

php – RESTful API中错误的最佳实践

猜你在找的PHP相关文章