为RESTful API设计返回值

Question

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

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

例如：

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

对于RESTful服务：

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

- Carsten E

Answer 1

使用供应商类型的HTTP内容协商。如果您请求同一资源的不同表示，请勿使用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"
}

供应商类型可以用于资源的两个方面。

- user5547025

Answer 2

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

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

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

- cassiomolin