返回多种 JSON 类型的 REST 端点

Question

我们正在讨论 REST 基础架构，因为其中一个端点目前可以返回两种不同类型的数据：

如果找不到任何对象，它会返回如下内容：

{
   "key1": "value1",
   "key2": "value2"
}

如果它可以找到任何数据，它会返回如下内容：

{
   "key3": "value3",
   "key4": [   {
      "key5": "value5",
      "output":       [
                  {
            "name": "value6",
            "value": "value7"
         },
                  {
            "name": "value8",
            "value": 0
         }
      ]
   }]
}

我认为这不是非常完整的 REST，但我对 REST 设计相对较新。

有哪些好的地方可以指导如何设计此类响应？

Answer 1

对此有很多意见。我的观点是，如果找不到任何对象，则返回 404。如果您找到一个或多个对象，您将返回一个 200 以及包含这些对象的正文。

如何在200 正文响应中构造这些对象取决于您。我的偏好一直是单个项目的直接 JSON 对象，或多个数组。

这里有一些例子：

GET /api/users/20000000 返回404

GET /api/users/1 返回 200，正文为 {"name":"John Smith","id":"1","email":"john@smith.net"}

GET /api/users 返回 200 的主体为 [{"name":"John Smith","id":"1","email":"john@smith.net"},{"name":"Jill Smith","id":"2","email":"jill@smith.net"},{"name":"Someone Else","id":"3","email":"someone@else.com"}]（注意数组格式）

GET /api/users/1,2 返回 200 的主体为 [{"name":"John Smith","id":"1","email":"john@smith.net"},{"name":"Jill Smith","id":"2","email":"jill@smith.net"}]（注意数组格式）

仅供参考，我必须为一个快递项目实现类似的东西，所以我用 booster http://github.com/deitch/booster 标准化了它