rest api 响应格式

Question

我是否应该将所有 api 响应视为“资源”并返回 JSON 对象或简单数组也合适？

例如，以下所有响应都有效吗？

GET /rest/someresource 应该返回 id 集合

1. [{id:1},{id:2}]
2. {{id:1},{id:2}}
3. [1,2]

GET /rest/someresource?id>0搜索大于零的id并返回id集合

1. [{id:1},{id:2}]
2. {{id:1},{id:2}}
3. [1,2]

Answer 1

收藏资源

返回一个资源数组是可以接受的——要么是 id 列表，要么是对象结构——这样的东西通常被称为“集合”资源。

查看http://51elliot.blogspot.com.au/2014/06/rest-api-best-practices-4-collections.html查看资源和收藏。

虽然 REST 不要求，但通常使用复数名词来指代集合资源 - 例如

/rest/someresources

REST 还需要使用已定义的媒体类型，并且有一些可用于协助收集，例如：

• Collection+json
  • 围绕项目列表提供包含元数据的结构，您可以在其中将每个项目的结构定义为资源
• HAL
  • 提供具有嵌入式集合和嵌入式资源的结构

还有many more

所有都提供了一个定义的结构，用于为您的资源或集合中的每个资源包含超媒体链接 - 如果您正在使用 REST，这是规范要求您必须做的事情之一（即使很多人不这样做） )。

您建议的 Json 结构

您建议的 json 结构上的一些更具体的 cmets：

选项 2 不是有效的 json。考虑：

{{id:1},{id:2}} 

一个 json 对象必须有一个名称：值对，例如

{somename:{id:1},someothername:{id:2}}

会有效 - 但不是很有用！

另外 - 严格来说，对于 json，名称应该用引号括起来。如果它是一个字符串，则该值可以用引号引起来。

因此，如果您不想使用上面提到的常用媒体类型，您的选项是 1 或 3。应该是：

• [{"id":1},{"id":2}]
• [1, 2]

两者都是有效的，但是如果您决定将来要返回的不仅仅是 id，选项 1 将让您更灵活地为数组的每个元素添加更多属性。例如在未来的某个时候，您可能会决定返回：

[{"id":1,"name":"fred"},{"id":2,"name":"wilma"}]

选项 3 将只能返回一个 id 列表。

所以我个人会选择选项 1。

Answer 2

取决于您的目标RESTful。

除了@Chris Simon 所说的，我还要补充一点，如果服务器只返回GET /rest/someresource 的ID，客户端将不得不重复调用GET /rest/someresource/{id} 之类的东西才能获取数据（它可以显示在 UI 上），对吧？这反过来只会增加服务器上的负载。如果 id 就足够了，您可能可以摆脱建议的解决方案。

此外，一旦你决定你最好保持一致。

鉴于第二个选项甚至无效，并且最后一个选项非常有限，我也会选择第一个选项 JSON。

Answer 3

为了清楚起见，我们在这里讨论的是同一资源的不同表示：

GET /rest/someresource[{id:1},{id:2}] 和 [1,2] 都是有效的回复，但你应该明确你想看哪一个，例如与prefer header。因此，通过Prefer: return=minimal，您将返回[1,2]，如果标头不存在，则返回[{id:1},{id:2}]。只要确保prefer header 是由vary header 注册的，否则你会遇到缓存问题。

由GET /rest/someresource?id>0 过滤您的收藏。因此，/rest/someresource?id>0 URI 要么标识不同的过滤集合资源，要么标识相同的集合资源，但使用过滤器查询字符串，您的客户端表明它正在等待资源的过滤表示，而不是完整表示。如果您不想使用首选标头，则可以通过最小表示来使用相同的标头：GET /rest/someresource?return=minimal。

请注意，如果您希望客户再次查询，则应在回复中向他们发送超链接。 REST 客户端必须从这些超链接中获取 URI（或 URI 模板），并且不应开始自行构建 URI。