9

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

如果出现错误，我应该使用

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?
    }
}
4

3 回答 3

12

当您查看可用的 HTTP 状态代码列表时，您会在某些时候意识到它们有很多，但单独使用它们本身并不能真正解释错误。

所以要回答你的问题，有两个部分。一个是：您的 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 接口本身就是一项艰巨的任务，但是存在的接口越多，积累的经验就越多。

编辑：

关于版本控制：将版本标记放入 URL 被认为是不好的做法，如下所示：example.com/api/v1/stuff它会起作用，但效果不好。

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

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

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

因此，当您创建使用 JSON 的 API 时，您无需处理通用 JSON。你处理一个具体的 JSON 结构，它对你的 API 来说是独一无二的。您可以并且可能应该Content-type在服务器发送的消息中指出这一点。“供应商”扩展就是为了这个：Content-type: application/vnd.IAMVENDOR.MYAPI+json将告诉世界基本数据结构是 ap​​plication/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 的客户端部分。

在版本中使用接受标头时，所有版本的资源 URL 都是相同的。客户端决定使用版本 1 或 2 请求资源，服务器可能非常友好并且仍然使用版本 1 响应来响应版本 1 请求，但所有版本 2 请求都使用新的和闪亮的版本 2 响应。

如果服务器无法响应版本 1 请求，他可以通过发送 HTTP 状态“406 Not Acceptable”告诉客户端（请求的资源只能根据请求中发送的 Accept 头生成不可接受的内容。）

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

总结一下：对于一个非常基本的 API，可能是内部的，使用有限，即使有一个版本也可能是矫枉过正。但你永远不知道这是否会在一年后成为现实。在 API 中包含版本号始终是一个非常好的主意。最好的地方是你的 API 将要使用的 mime 类型。检查单个现有版本应该是微不足道的，但您可以选择稍后透明升级，而不会混淆现有客户端。

于 2013-03-24T15:47:54.847 回答
2

我不会对所有事情都使用 200 状态。那只会令人困惑。

Jquery 允许您以不同的方式处理不同的响应代码，已经有内置的方法可以利用它们在您的应用程序中使用它们，当您的应用程序增长时，您也可以提供该 API 供其他人使用。

编辑：另外我强烈推荐观看这个关于 Laravel 和 API 开发的演讲：

http://kuzemchak.net/blog/entry/laracon-slides-and-video

于 2013-03-24T16:27:50.240 回答
1

有一些 HTTP 状态代码列表Illuminate\Http\Response扩展至Symfony\Component\HttpFoundation\Response. 你可以在课堂上使用它。

例如：

use Illuminate\Http\Response as LaravelResponse;
...
return Response::json('User Exists', LaravelResponse::HTTP_CONFLICT);

它更具可读性。

于 2014-03-12T15:05:12.187 回答