设计RESTful API的返回值

Question

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

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

示例：

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

对于RESTful服务：

• 返回值（car-objects）是否具有相同的属性？
• 详细信息对象可以比列表对象具有更多属性吗？
• 在哪种情况下对象必须相同？

Answer 1

使用查询参数来请求字段子集

您可以在两种情况下返回相同的表示形式，并支持使用查询参数过滤要返回的字段：

GET /api/cars?fields=color,year HTTP/1.1
Host: example.com
Accept: application/json

使用自定义媒体类型返回一组预定义字段

另一种方法是为资源的部分表示定义自定义媒体类型。

例如，您可以使用以下（或两种）媒体类型之一来检索资源集合的完整表示形式：

GET /api/cars HTTP/1.1
Host: example.com
Accept: application/json

GET /api/cars HTTP/1.1
Host: example.com
Accept: application/vnd.company.full+json

以下内容返回您资源的部分表示（您将在部分表示中包含的字段由您决定）：

GET /api/cars HTTP/1.1
Host: example.com
Accept: application/vnd.company.partial+json

Answer 2

对供应商类型使用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"
}

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