设计RESTful API的返回值

有很多有关 RESTful 服务的文档。我需要有关返回陈述的更多信息。

设计 RESTful 服务返回值的最佳方法是什么？

Example:

• GET /rest/cars: 列出汽车
• GET /rest/cars/1234： ID 为 1234 的汽车

对于 RESTful 服务：

• 返回值（汽车对象）是否应该具有相同的属性？
• 详细信息对象是否可以比列表对象拥有更多属性？
• 在什么情况下对象必须相同？

Use HTTP 内容协商与供应商类型。如果您请求同一资源的不同表示形式，请勿使用 URL 查询参数。

请求简短的表示application/vnd.com.example.cars.short+json of list

GET http://example.com/rest/cars
Accept: application/vnd.com.example.cars.short+json

回复：

200 OK
Content-Type: application/vnd.com.example.cars.short+json

[
  {
    "id": 12,
    "brand": "Ford"
  },
  {
    "id": 34,
    "brand": "Volkswagen"
  },
  {
    "id": 1234,
    "brand": "Tesla"
  }
]

请求长表示application/vnd.com.example.cars.long+json单车的

GET http://example.com/rest/cars/1234
Accept: application/vnd.com.example.cars.short+json

Response

200 OK
Content-Type: application/vnd.com.example.cars.long+json

{
  "id": 1234,
  "brand": "Tesla",
  "manufactured": "2016-03-15",
  "color": "black"
}

供应商类型可用于both资源。