rest - RESTful API 的设计返回值

Question

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

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

例子:

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

对于 RESTful 服务:

• 返回值(汽车对象)是否应该具有相同的属性？
• 细节对象可以比列表对象有更多的属性吗？
• 在什么情况下对象必须相同？

Answer 1

使用HTTP Content negotiation与供应商类型。如果请求同一资源的不同表示，请不要使用 URL 查询参数。

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

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

响应

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

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

供应商类型可用于两种资源。