应该在REST API设计中使用http状态代码

Question

例如，基于SOAP的http REST的优势之一是REST利用机器语言/约定传达了很多含义（即http POST表示创建，http DELETE表示删除。等等。所以它消除了许多模糊性和错误的空间，这些错误与所有协议（例如肥皂）免费相关。

说，我想知道是否可以将这个概念扩展到http响应类型...特别是当涉及到错误时......所以我想说这个api调用，我想得到这个数字我周围可用的司机：

get api/drivers

如果找到了一些驱动程序..那么通常你会给json返回驱动程序数量+详细信息等。但是当找到0个驱动程序时会发生什么？你应该以0的相同格式返回数据吗？或者您应该使用http响应代码并返回http 404代码？

尽管使用404代码与约定优于配置的想法一致...并让机器语言完成大部分解释/解释..我发现一些工程师抱怨404响应更像是抛出异常当用户附近有0个驱动程序是完全正常的时候，好像出了什么问题。

更新：

在找到附近司机/餐馆等的数量的情况下......答案可能是显而易见的......但是当您创建一个假设的休息api时会发生什么......例如这个

get api/drivers/eta

这意味着获得最近的驱动程序的eta ..在没有驱动程序的地方会发生什么？在这里使用404或返回正常200会更有意义并在json机构中解释没有驱动程序存在吗？

Answer 1

对集合资源的GET请求可以返回空集合。此响应为200 OK，因为（空）集合存在。返回404 Not Found意味着存在 no 集合，但事实并非如此。

请求：

GET /restaurants

响应：

200 OK
Content-Type: application/json

{
  "count": 0,
  "restaurants": []
}

Answer 2

我在Build APIs You Won't Hate的端点理论章节中介绍了这一点，但我可以快速推断。

  

...所以我想说这个api电话，我想知道我周围可用的司机数量：

     

获取api / drivers

Weeeeell它不是“在你身边”，除非你传递一些坐标，因为它是无状态的，我们不希望某些rando背景逻辑跟踪用户位置。维持这种状态将是艰难和奇怪的，所以我们只是根据要求传递它。

GET /api/drivers?lat=X&lon=Y

  

如果找到了一些餐馆..那么通常你会带着餐馆的数量和细节等返回json ..但是当找到0家餐馆时会发生什么？你应该以0的相同格式返回数据吗？或者您应该使用http响应代码并返回http 404代码？

我们从司机跳到这里让我感到困惑的餐馆，但回答更一般的问题：空集是404？

都能跟得上！集合是一种资源（哇！）存在的实际事物。如果你有一袋扳手，那么这个包就像扳手一样资源。与我一起？

所以，你有这个扳手包。你借出了所有的扳手，但你仍然有这个包。或者也许你刚拿到包，没有扳手到了。或者也许有人问你是否有紫色扳手。

所有这些请求都将返回一个空包的扳手。

基本上，GET /restaurants应该总是200 OK，直到您弃用的那一天，并从您的API中删除餐馆的概念。如果没有餐馆，那没关系，你有一排空的餐馆。

  

当你创建一个假设的休息api时会发生什么......比如这个

     

获取api / drivers / eta

     

这意味着得到最近的司机的eta ..在没有司机的地方会发生什么？在这里使用404或返回正常200会更有意义并在json机构中解释没有驱动程序存在吗？

这将是你的REST API中的一个rando-RPC终端，所以要为那些初学者做好准备。

如果您有一个特定的订单，您希望看到驱动程序进展，那么您不需要这个任意的RPC样式端点。你能做的就是：

GET /apis/orders/<uuid>

这可能很容易在几分钟内产生“eta”字段，但我认为另一个端点可以改善这一点：

GET /apis/orders/<uuid>/updates

这个清单会在厨房完成准备时有更新，另一个是司机开机时，另一个是驾驶员中途，另一个是司机拉起时等等。

同样，如果有没有更新，那只是一个空包更新。

Answer 3

在设计解决方案时，请考虑以下因素：易于使用，简单实施和维护。

关于HTTP错误代码：虽然它比定义自己的代码有优势，但使用它可能会干扰正常的HTTP错误，从而限制了您将来使用这些日志的选项，如质量分析，入侵检测......

然后，主叫方必须处理并区分HTTP错误代码和application / api错误代码。因此，如果你得到一个500将这是一个内部服务器错误的一些未捕获的错误或有人刚刚解雇它，因为他们错过了一些强制性的参数。如果你得到404，这是因为你错过了输入你的URI（或更改了URL），或者因为服务器没有找到你要求的一些数据，例如在上面的例子中“没有找到出租车”

看看像apis一样实现的一些api，FB ..他们在返回的回复中定义了返回码（无论是json / xml / text ......）

Answer 4

首先，/ api / drivers / eta不代表服务器上的资源。我们正在尝试将其建模为不是RESTful设计的资源;但我们假设您的业务需要支持这样的端点。当在服务器上找不到由URL标识的资源时，应使用404。所以在这种情况下，200 OK和空响应更有意义。或者，如果您希望将此视为错误情况，则可以在响应有效内容中使用422或400以及相应的消息

请求：

GET / api / drivers / eta

响应：

200 OK Content-Type：application / json

{   ＆＃34;计数＆＃34;：0，   ＆＃34;司机＆＃34;：[] }