php - RESTful API错误的最佳实践

Question

在RESTful API中返回HTTP状态代码的最佳实践是什么？我在我的PHP框架中使用Laravel 4。

如果发生错误，我应该使用

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

或者

包含success的标志

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

或者

使用200而不是4xx，依靠success来确定是否存在错误

return Response::json([
    'success' => false,
    'data' => 'User Exists'],
    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?
    }
}

Answer 1

当您查看list of available HTTP status codes时，您会在某种程度上意识到它们很多，但是单独使用它们并不能真正解释错误。

因此，回答您的问题有两个部分。一个是:您的API如何传达错误原因，并添加有用的信息，API用户(在大多数情况下是另一位开发人员)可以阅读并采取行动。您应该添加尽可能多的机器可读和人类可读的信息。

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

后一部分实际上比一件事情要难。在明显的情况下，使用404来指示“未找到”。对于服务器端的任何错误，则为500。

我不会使用状态401，除非我真的想在存在HTTP身份验证凭据的情况下允许操作成功。 401通常会触发浏览器中的对话框，这很糟糕。

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

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

根据我的经验，很容易简单地选择一个状态代码并使用它，但是很难一致地并按照现有标准进行操作。

但是，我不会仅仅因为其他人可能会提示而在这里停下来。 :)正确实现RESTful接口(interface)本身是一项艰巨的任务，但是接口(interface)越多，经验就越多。

编辑:

关于版本控制:将版本标记放入URL中被认为是一种不好的做法，例如:example.com/api/v1/stuff可以，但是效果不好。

但第一件事是:您的客户如何指定他想要获取的表示形式，即他如何决定获取JSON或XML？答:带有Accept header 。他可以发送JSON的Accept: application/json和XML的Accept: application/xml。他甚至可能接受多种类型，由服务器决定然后返回什么。

除非服务器被设计为使用一种以上的资源表示形式(JSON或XML，由客户端选择)来回答，否则客户端确实没有太多选择。但是让客户端至少发送“application/json”作为他唯一的选择，然后返回头Content-type: application/json作为响应仍然是一件好事。这样，双方就清楚自己希望对方看到什么样的内容。

现在是版本。如果将版本放入URL中，则可以有效地创建不同的资源(v1和v2)，但实际上，您只有一个资源(= URL)，并且使用不同的方法来访问它。当请求的参数和/或响应中的表示形式的更改与当前版本不兼容时，必须创建API的新版本。

因此，当您创建使用JSON的API时，不会处理通用JSON。您要处理一个特定的JSON结构，该结构在某种程度上是您的API特有的。您可以并且可能应该在服务器发送的Content-type中指出这一点。这里有“vendor”扩展名:Content-type: application/vnd.IAMVENDOR.MYAPI+json会告诉世界基本数据结构是application/json，但是真正由您公司和您的API告诉您期望使用哪种结构。这正是API请求的版本适合的位置:application/vnd.IAMVENDOR.MYAPI-v1+json。

因此，您希望客户端将发送Accept: application/vnd.IAMVENDOR.MYAPI-v1+json header ，而不是将版本放在URL中，并且您也将使用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 header 时，所有版本的资源URL均相同。客户端决定请求版本1或2的资源，而服务器可能是如此，并且仍然使用版本1的响应来回答版本1的请求，但是所有版本2的请求都使用新的 Shiny 版本2的响应。

如果服务器无法回答版本1请求，则他可以通过发送HTTP状态“406 Not Acceptable ”来告知客户端(根据请求中发送的接受 header ，请求的资源只能生成 Not Acceptable 内容。)

客户端可以发送包含两个版本的accept header ，这使服务器能够以他最喜欢的一个版本进行响应，即，智能客户端可以实现版本1和2，现在将两个版本都作为accept header 发送，并等待服务器升级从版本1到版本2。服务器将在每个响应中告知它是版本1还是版本2，客户端可以采取相应的行动-他不需要知道服务器版本升级的确切日期。

总结一下:对于一个非常有限的(可能是内部的)非常基本的API，即使拥有一个版本，使用也可能是过大的。但是您永远不知道从现在开始一年后这是否会成真。在API中包含版本号始终是一个非常好的主意。最好的地方是您的API将要使用的mime类型。检查单个现有版本应该很简单，但是您可以选择以后透明升级，而不会混淆现有客户端。