rest api 响应格式
rest api response format
我是否应该将所有 api 响应视为 "resource" 和 return 一个 JSON 对象或简单数组也合适？
例如，以下所有回答都有效吗？
GET /rest/someresource 应该 return id 集合
[{id:1},{id:2}]{{id:1},{id:2}}[1,2]
GET /rest/someresource?id>0 搜索大于零的 ID 和 return ID 集合
[{id:1},{id:2}]{{id:1},{id:2}}[1,2]
Collection 资源
return 资源数组是可以接受的 - id 列表或 object 结构 - 这种东西通常被称为 'collection' 资源。
请参阅 http://51elliot.blogspot.com.au/2014/06/rest-api-best-practices-4-collections.html 查看资源和 collections。
虽然 REST 不要求，但通常使用复数名词来指代 collection 资源 - 例如
/rest/someresources
REST 还需要使用定义的媒体类型，并且有一些可以帮助 collections，例如：
- Collection+json
- 围绕项目列表提供元数据结构，您可以在其中将每个项目的结构定义为您的资源
- HAL
- 提供具有嵌入式 collection 和嵌入式资源的结构
所有都提供了一个定义的结构，用于包含您的资源的超媒体链接，或者您 collection 中的每个资源 - 如果您正在做 REST，这是规范规定您必须做的事情之一（即使尽管很多人不这样做）。
您提出的 Json 结构
对您提议的 json 结构的一些更具体的评论：
选项 2 无效 json。考虑：
{{id:1},{id:2}}
一个json object必须有一对name:value，例如
{somename:{id:1},someothername:{id:2}}
会有效 - 但不是很有用！
此外 - 严格针对 json，名称应该用引号引起来。如果该值是字符串，则该值可以用引号引起来。
因此，如果您不想使用上面提到的常用媒体类型，您的选项是 1 或 3。应该是：
[{"id":1},{"id":2}][1, 2]
两者都有效，但是选项 1 将使您更灵活地向数组的每个元素添加更多属性，如果您决定在将来希望 return 多于一个 id。例如在未来的某个时候，您可能会决定 return:
[{"id":1,"name":"fred"},{"id":2,"name":"wilma"}]
选项 3 将只能return ID 列表。
所以我个人会选择选项 1。
取决于您RESTful的目标。
除了@Chris Simon 所说的之外，我还要补充一点，如果服务器只在 GET /rest/someresource 处提供 return 个 ID，客户端将不得不重复调用类似 GET /rest/someresource/{id}为了获取数据（可以显示在UI上），对吧？这反过来只会增加服务器的负载。如果 id 就足够了，您可能可以摆脱建议的解决方案。
此外，一旦您决定最好保持一致。
鉴于第二个选项甚至无效，最后一个选项非常有限，我也选择第一个选项，JSON。
为了清楚起见，我们在这里讨论的是同一资源的不同表示形式：
By GET /rest/someresource [{id:1},{id:2}] 和 [1,2] 都是有效的回复，但是你应该明确你想看哪一个，例如使用 prefer header. So by Prefer: return=minimal you would return [1,2] and if the header is not present, then [{id:1},{id:2}]. Just make sure that the prefer header is registered by the vary header，否则您将遇到缓存问题。
通过 GET /rest/someresource?id>0 你过滤了你的 collection。因此，/rest/someresource?id>0 URI 标识不同的过滤后的 collection 资源，或者它标识相同的 collection 资源，但是使用过滤器查询字符串，您的客户端表明它正在等待过滤后的表示资源而不是完整的表示。如果你不想使用 prefer header: GET /rest/someresource?return=minimal.
，你可以通过最小表示使用相同的
请注意，如果您希望您的客户再次查询，那么您应该在回复中向他们发送超链接。 REST 客户端必须从这些超链接中获取 URI（或 URI 模板），并且不应开始自行构建 URI。
我是否应该将所有 api 响应视为 "resource" 和 return 一个 JSON 对象或简单数组也合适？
例如，以下所有回答都有效吗？
GET /rest/someresource 应该 return id 集合
[{id:1},{id:2}]{{id:1},{id:2}}[1,2]
GET /rest/someresource?id>0 搜索大于零的 ID 和 return ID 集合
[{id:1},{id:2}]{{id:1},{id:2}}[1,2]
Collection 资源
return 资源数组是可以接受的 - id 列表或 object 结构 - 这种东西通常被称为 'collection' 资源。
请参阅 http://51elliot.blogspot.com.au/2014/06/rest-api-best-practices-4-collections.html 查看资源和 collections。
虽然 REST 不要求，但通常使用复数名词来指代 collection 资源 - 例如
/rest/someresources
REST 还需要使用定义的媒体类型，并且有一些可以帮助 collections，例如：
- Collection+json
- 围绕项目列表提供元数据结构，您可以在其中将每个项目的结构定义为您的资源
- HAL
- 提供具有嵌入式 collection 和嵌入式资源的结构
所有都提供了一个定义的结构，用于包含您的资源的超媒体链接，或者您 collection 中的每个资源 - 如果您正在做 REST，这是规范规定您必须做的事情之一（即使尽管很多人不这样做）。
您提出的 Json 结构
对您提议的 json 结构的一些更具体的评论：
选项 2 无效 json。考虑：
{{id:1},{id:2}}
一个json object必须有一对name:value，例如
{somename:{id:1},someothername:{id:2}}
会有效 - 但不是很有用！
此外 - 严格针对 json，名称应该用引号引起来。如果该值是字符串，则该值可以用引号引起来。
因此，如果您不想使用上面提到的常用媒体类型，您的选项是 1 或 3。应该是：
[{"id":1},{"id":2}][1, 2]
两者都有效，但是选项 1 将使您更灵活地向数组的每个元素添加更多属性，如果您决定在将来希望 return 多于一个 id。例如在未来的某个时候，您可能会决定 return:
[{"id":1,"name":"fred"},{"id":2,"name":"wilma"}]
选项 3 将只能return ID 列表。
所以我个人会选择选项 1。
取决于您RESTful的目标。
除了@Chris Simon 所说的之外，我还要补充一点，如果服务器只在 GET /rest/someresource 处提供 return 个 ID，客户端将不得不重复调用类似 GET /rest/someresource/{id}为了获取数据（可以显示在UI上），对吧？这反过来只会增加服务器的负载。如果 id 就足够了，您可能可以摆脱建议的解决方案。
此外，一旦您决定最好保持一致。
鉴于第二个选项甚至无效，最后一个选项非常有限，我也选择第一个选项，JSON。
为了清楚起见，我们在这里讨论的是同一资源的不同表示形式：
By GET /rest/someresource [{id:1},{id:2}] 和 [1,2] 都是有效的回复，但是你应该明确你想看哪一个，例如使用 prefer header. So by Prefer: return=minimal you would return [1,2] and if the header is not present, then [{id:1},{id:2}]. Just make sure that the prefer header is registered by the vary header，否则您将遇到缓存问题。
通过 GET /rest/someresource?id>0 你过滤了你的 collection。因此，/rest/someresource?id>0 URI 标识不同的过滤后的 collection 资源，或者它标识相同的 collection 资源，但是使用过滤器查询字符串，您的客户端表明它正在等待过滤后的表示资源而不是完整的表示。如果你不想使用 prefer header: GET /rest/someresource?return=minimal.
请注意，如果您希望您的客户再次查询，那么您应该在回复中向他们发送超链接。 REST 客户端必须从这些超链接中获取 URI（或 URI 模板），并且不应开始自行构建 URI。