Question

我一直在网上搜索这个并且找不到一个非常简单的问题的答案：对于特定资源的所有HTTP谓词，JSON格式是否相同？

例如：

GET http://example.com/api/articles返回

[
  {
    id: 1,
    ref: "21313-453542"
  },
  {
    id: 2,
    ref: "23424-234243"
  }, ...
]

GET http://example.com/api/articles/2返回

{
  id: 2,
  ref: "23424-234243",
  name: "Cofee",
  price: 23,
  provider: "112-411",
}

这是一个好的做法还是JSON对象应始终保持一致的格式？为了使自己清楚，如果格式应该是一致的，那么第一个请求应该返回如下内容：

[
  {
    id: 1,
    ref: "21313-453542",
    name: "Oranges",
    price: 34,
    provider: "2424-12",
  }
  {
    id: 2,
    ref: "23424-234243",
    name: "Cofee",
    price: 23,
    provider: "112-411",
  }
]

Answer 1

在我看来，你应该为你给出的端点返回的JSON数据使用相同的“模式”作为示例，因为我希望http://example.com/api/articles/2 API调用可用于获取单个文章而http://example.com/api/articles可用于获取所有可用的文章，但文章数据表示是相同的。

如果要提供文章实体的“紧凑”表示，例如仅使用第一个JSON表示中的id和ref属性，则应提供不同的API端点，例如：

http://example.com/api/articles-refs或http://example.com/api/articles/refs

你应该对任何合适的HTTP动词采用这种表示策略（例如GET，POST，PUT），而像DELETE这样的动词通常只需要删除实体的 id ，因为附加实体属性对特定的API操作无用。

这导致了一致且易于使用的API，恕我直言。

无论如何，您应始终记录您的API，以便向API使用者提供有关可用操作，语义和输入/输出数据的JSON架构的信息。

您可以将Swagger / OpenAPI用于API文档。如果您使用Java来实现您的API，我就此发布了ar article on DZone。

Answer 2

通常至少有两种观点＆＃39;相同数据的摘要 - 包含用于在列表中返回的有限信息的摘要，以及包含仅返回一个实体的查询的所有信息的详细视图。在列表中返回非常详细的信息的问题在于它通常涉及对数据库的更复杂，性能更低的查询。

因此，以这种方式分割您的观点是一个好主意。

Answer 3

我的建议：

格式应保持一致。它使文档更容易。
用 uri 字段替换所有 id 字段。如果客户端总是看到URI而不是ID，那就更好了。

例如：

{
  uri: "http://example.com/api/articles/2",
  ref: "23424-234243",
  name: "Cofee",
  price: 23,
  provider: "112-411",
}

Answer 4

为您拥有的每种资源定义对象模式（通常是地图）。

/ api / resources（GET） - 应列出所有资源

/ api / resources / $ resource_id（GET） - 应返回特定资源

/ api / resources（POST） - 应该创建并返回新创建的资源

/ api / resources / $ resource_id（PUT） - 应返回特定的已编辑资源

/ api / resources / $ resource_id（DELETE） - 设置HTTP 204响应代码（无内容）

只有列表资源api才能提供对象列表。所有其他API类型只能返回对象映射。

带宽优化： 如果要限制发送到客户端的数据，可以支持查询参数字段。如果未给出此字段，则可以返回资源的整个对象表示形式。 / API /资源？字段= ID，参考

REST API - JSON格式一致性

4 个答案: