休息API响应格式(rest api response format)

休息API响应格式(rest api response format)

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

例如以下所有回复是否有效？

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

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

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

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

Should I treat all api response as "resource" and return a JSON object or simple array would be appropriate as well ?

for instance are all of the below responses valid?

GET /rest/someresource should return collection of ids

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

GET /rest/someresource?id>0 search for ids bigger than zero and return collection of ids

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

最满意答案

收集资源

返回一个资源数组 - 无论是id列表还是对象结构 - 都是可以接受的 - 这种东西通常被称为“集合”资源。

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

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

/rest/someresources

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

收藏+ JSON 在项目列表周围提供包含元数据的结构，其中您将每个项目的结构定义为资源 HAL 提供了一个嵌入式集合和嵌入式资源的结构

还有更多

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

您提议的Json结构

关于你提出的json结构的一些更具体的评论：

选项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。

Collection Resources

It is acceptable to return an array of resources - either a list of ids, or object structures - such a thing is commonly known as a 'collection' resource.

See http://51elliot.blogspot.com.au/2014/06/rest-api-best-practices-4-collections.html for an examination of resources and collections.

While not required by REST, it's common to use a plural noun to refer to a collection resource - e.g.

/rest/someresources

REST also requires the use of defined media types, and there are a couple available to assist with collections, e.g.:

Collection+json Provides a structure with meta data around a list of items wherein you define the structure of each item as your resource HAL provides a structure with embedded collections and embedded resources

And many more

All provide a defined structure for including hypermedia links for your resource, or each resource in your collection - and if you are doing REST this is one of the things that the spec says you MUST do (even though many people don't).

Your Proposed Json Structures

Some more specific comments on your proposed json structures:

Option 2 is not valid json. Consider:

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

A json object must have a name:value pair, e.g.

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

would be valid - but not very useful!

Also - strictly for json, the name should be enclosed in quotes. the value may be enclosed in quotes if it is a string.

So if you don't want to use a commonly used media type as referenced above, your options are 1 or 3. which should be:

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

Both are valid, however option 1 will give you more flexibility to add more properties to each element of the array if you decide in the future you would like to return more than an id. e.g. at some point in the future you might decide to return:

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

Option 3 will only ever be able to return a list of ids.

So personally I would go with option 1.