如何设计一个REST API，以请求资源中的特定字段

Question

我在一个Web服务中有一个RESTful API，其中包含用户、帖子等资源。当我请求帖子列表（GET /posts）时，我只想获取每个帖子的有限数据（例如主题、作者姓名）。当我请求具体的帖子（GET /posts/42）时，我希望获取完整的帖子对象字段列表，包括大段的帖子内容、关于点赞数和评论数的附加信息。 我想解决这个问题可能有很多方法。

在我看来，最明显的三种方法是：

1. 在每个请求上明确指定字段列表（例如/posts?fields=subject,author_name和/posts/42?fields=subject,body,createAt,author_name,comments_count,likes_count等）。 2. 仅在字段列表与默认字段列表不同时明确指定字段列表。 3. 如果所需字段集与默认字段集不同，则指定应从默认字段集中排除（或包含）的字段列表。

我想为我的客户构建一个清晰而有用的API。我应该选择哪种方式呢？

- Ivan Velichko

Answer 1

我会选择第二个选项。

如果消费者只请求资源URL（/posts/42），他们将收到默认字段。

然后，消费者可以通过在查询字符串中定义值来更改默认响应，例如：

/posts/42/fields?subject,author_name 这在过去对我非常有效，也是一些其他知名API的工作方式，例如Facebook。

尽管我会更改请求为：

/posts/42?fields=subject,author_name /post/42是资源，而不是字段。

- Dan Rowlands

---

我同意。它提供了低门槛，使开发人员可以探索并轻松查看默认字段，但仍然具有灵活性，如果需要，可以精确地请求所需内容。 - theon

我也选择选项（2），但我允许使用 fields=* 来获取所有字段，以便轻松查询完整集合（特别是对于想要知道或双重检查该集合的开发人员来说）。 - Lawrence Dol

Answer 2

Facebook的GraphQL是一种替代RESTful API请求所需字段的选择。它仍处于非常早期的阶段，但似乎非常有前途。

来自GraphQL介绍，作者Nick Schrock：

A GraphQL query is a string interpreted by a server that returns data in a specified format. Here is an example query:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50)  {
      uri,
      width,
      height
    }
  }
}

(Note: this syntax is slightly different from previous GraphQL examples. We've recently been making improvements to the language.)

And here is the response to that query.

{
  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}

- ascrookes