Question

我是第一次设计REST API，所以我认为这是一个关于其设计的基本问题。

我希望文件集合返回所有可用文件资源的ID（或链接），而不是检索完整的表示，因为它会有太多的数据。

GET /files        # return the full representation of a collection of resources
GET /files/{id}   # return the full representation of a single resource

我不知道将它拆分为两个不同的资源是否更好：

GET /fileids      # return only IDs
GET /files/{id}   # return the full representation of a single resource

你的方法是什么？

Answer 1

自定义媒体类型

您可以使用自定义媒体类型来表示资源的完整代表，也可以使用自定义媒体类型来获取文件的标识符。

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

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

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

以下媒体类型仅检索文件的标识符：

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

查询字符串参数

或者，您可以支持使用查询字符串参数选择要检索的字段。

使用以下内容检索文件集合的完整表示形式：

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

以下内容仅检索文件的标识符：

GET /api/files?fields=id HTTP/1.1
Host: example.com
Accept: application/json

field查询参数可以支持以逗号分隔的值列表，允许选择多个字段/属性：

GET /api/files?fields=id,name,author HTTP/1.1
Host: example.com
Accept: application/json

Answer 2

做吧。

我将其称为标准RESTful API设计模式，在集合资源中具有缩写的资源表示，并且仅在您的实体资源上具有完整表示。

所以/files会返回类似的内容：

[
  {
    name: "foo",
    url: "example.org/files/3321"
  },
  {
    name: "bar",
    url: "example.org/files/3192910"
  }
]

虽然/files/3321返回完整的file表示

{
  name: "foo",
  self: "example.org/files/3321"
  encoding: "UTF-8",
  type: "xml-document"
}

检索ID的集合，而不是REST中资源的完整表示

2 个答案:

自定义媒体类型

查询字符串参数