RESTAPI客户端指定所需响应细节的好方法？

我正在设计一个RESTAPI，几个客户端将使用它来查询数据存储库。我预计这些客户在回复的数量/详细程度方面会有不同的需求

假设我可以查询一组书籍。一本书可能有很多属性（比任何一个客户机可能感兴趣的属性都多），甚至可能有子资源，客户机可能会请求大量的书，导致响应体比所需的大

因此，我正在研究优化响应大小的方法。这样做的目的是为API客户机提供一些方法来指定响应中应该包含多少细节

我很想知道这个问题以前是如何解决的；哪种机制在实践中工作得很好，哪种没有，哪种API设计特别是RESTful的，哪种不是RESTful的，等等

我可以通过以下几种方式思考客户机如何为响应指定所需的详细级别：

• 使用

  GET

  或

  HEAD

  HTTP方法/动词。前者将返回所有细节，前者仅返回子集
  这种方法只允许我们区分两个层次的细节，因此使用有限

• 具有查询字符串参数，该参数指定（按名称）响应中应返回的属性。例如：

  GET /books?include=title,author,publisher,...,preview
  

  这提供了几乎无限的灵活性，但这种灵活性可能很难实际实现和处理（在客户端和服务器端）

• 使用不同的媒体类型（每个详细级别有一种不同的媒体类型），通过

  Accept:

  标题选择
  我真的不想走那条路。我不确定媒体类型是否适合此用途，而且世界可能不需要更多的自定义媒体类型

• 使用

  配置文件

  关系/媒体类型参数。这似乎更好一些（不需要额外的媒体类型），但我仍然不确定媒体类型是否是选择响应“内容”的正确方法。它们似乎更适合单独指定响应的“方式”（格式）

• 对于图书收藏（

  /books？publishedIn=1980年代

  ），只返回所有可用数据的一小部分，最重要的是，可以查询每本书的

  href

  ，以获取关于一本书的完整数据
  这种方法至少有两个问题：

• 除了

  href

  链接之外，收集响应中还包括哪些属性？理想情况下，只有足够的额外数据满足大多数客户的需求；否则

• 客户将不得不执行大量额外的查询（每本书一个）来收集他们需要的所有数据

---

可能有更多的策略来选择所需的详细程度。我有兴趣了解什么在实践中工作得很好，而不会严重影响RESTfulity。

我认为这主要取决于您希望为API客户机提供多少灵活性

如果您知道数据的不同用途，那么可能需要定义一些API可以返回的可用格式

例如，使用此结构：

 GET /books (with a default format if nothing is specified)
 GET /books/minimal 
 GET /books/full 
 GET /books/otherformat

请注意，如果您不想复制端点，也可以使用此URL结构：

GET /books?format=minimal

然而，在任何一种情况下，这都会迫使您确切地知道客户在任何给定时间都需要或想要什么数据

我不会依赖媒体类型，因为这可能比使用RESTAPI的其他更标准的方式更让用户困惑

[编辑]

---

此外，如果您决定指定要返回的全部恶魔列表，并发现GET请求不够，您可以参考此列表，以获得另一种使用POST请求的方法

同时，我发现GraphQL（）非常接近我所寻找的。然而，我接受你的答案，因为它有很好的常识，而且可能更容易实现。非常感谢。