我目前正在尝试实施一个API，它将为我的客户提供内容，而且我对如何正确设计我的API有点不确定。特别是我的问题是：
让客户提出多个请求的特定API以特定方案提供服务是否更好？或者更好的方法是拥有一个服务于每个可能值的全能API，以便最大限度地减少客户端的请求使。
例如，在列出带有description / titles / tags / etc的图片的应用程序中，会出现两种情况：
第1页：
现在我可以用两种方式设计它：
（1）
GET /api/v1/pictures
返回包含所有信息的JSON，例如：
[
{
"pictureUrl": "someUrl",
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation",
{
]
（2）
GET /api/v1/pictures
使用Ids返回图片数组：
[
{
"pictureId" : "someId",
"pictureUrl": "someUrl"
}
]
（3）
GET /api/v1/picture/{id}
返回附加图片数据：
{
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation"
}
显然，在第一个版本中，客户端只需要执行1个请求。使用X图片和Y属性，这将是一个相当大的JSON响应，但是客户端不需要查询显示其他信息的任何其他信息。
这些风景中是否有指导或最佳实践？
我个人更喜欢方案2，因为它使API更具体，服务器开发更容易（想象多个表，多个连接以获取所有信息）。此外，它认为API不太容易改变，因为每种方法都是特定的并返回正确的内容。 例如：
如果我决定添加不同类型的图片（称之为媒体内容），并且可能是视频或gif，......，更改现有API将意味着更改返回类型。客户端必须分析返回的JSON以确定它正在处理的内容类型等。
我知道这是一个相当普遍的问题而且可能没有正确的答案，我希望在我下定决心之前听到一些意见。
答案 0 :(得分：2)
答案是：这取决于。基本上，您应该在SRP之后提供单独的端点 - 它也适用于REST设计。
还要注意应用程序无论如何都会进行多次调用 - 每个图像都会单独下载。
哪种客户端与应用程序（移动或网络/桌面）进行交互也很重要。在移动互动的情况下，在尽可能少的请求中提供所有必要信息是很好的 - 您可以节省宽带 - 而且通常可以更快地运行。
在这种特殊情况下，您还可以使用一种资源查询语言 - RQL。它将如下工作：
GET /pictures/
返回基本信息：例如ID和pictureURL。
GET /pictures/{ID}
返回有关图片的全部可用数据。这是您已经定义的内容。我们的想法是扩展第一个端点，使其返回通过fields查询参数传递的所有字段。
GET /pictures/?fields=pictureURL,ID,tags
通过这种方式，您可以获得返回所有图像的快速端点，一个用于返回图像详细信息的单独端点，如果消费者希望最大限度地减少呼叫次数，则可以提供灵活的API。
P.S。请从URL中删除版本控制 - 标题更适合版本控制。
答案 1 :(得分：1)
您可以将顺序指令包装在单个对象中。
拥有可以处理每个组合请求的API会导致方法数量呈指数级增长。进行多次单独调用将使得很难确保操作是原子操作的（您可以将move请求作为copy + delete请求传递，但如果只有第一个请求通过呢？）。< / p>
发送指令列表后跟校验和将避免这两个问题。