json - 服务器客户端应用程序API设计

Question

我目前正在尝试实现一个 API 来为我的客户提供内容，但我不确定如何为此正确设计我的 API。特别是我的问题是:

以客户端发出多个请求为代价让特定的 API 服务于特定的场景更好，还是让一个全能的 API 服务于每个可能的值以最小化客户端必须的请求更好？制作。

例如，在列出带有描述/标题/标签/等的图片的应用程序中，有两种情况:

第 1 页:

• 只在网格中显示图片。列出所有图片(或数量有限，比如 100 张)
• 点击图片打开 View 并显示其他信息:描述、标题、位置、标签、文本、评论。

现在我可以用两种方式设计它:

(1)

GET /api/v1/pictures 

返回包含所有信息的 JSON，例如:

[
{
"pictureUrl": "someUrl",
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation",
{
]

(2)

GET /api/v1/pictures 

返回带有 ID 的图片数组:

[
{
"pictureId" : "someId",
 "pictureUrl": "someUrl"
}
]

(3)

GET /api/v1/picture/{id}

返回附加图片数据:

{
"text": "someText",
"description": "someDesc",
"tags": "someTags",
"location": "someLocation"
}

显然在第一个变体中，客户端只需要做一个请求。使用 X 图片和 Y 属性，这将是一个相当大的 JSON 响应，但是客户端不需要查询任何显示附加信息的附加信息。

在这类场景中是否有指南或最佳实践？

我个人更喜欢方案 2，只是因为它使 API 更具体并且服务器开发更容易(想象多个表，多个连接以获取所有信息)。此外，感觉 API 将不太容易更改，因为每个方法都是特定的并返回正确的内容。例如:

如果我决定添加不同类型的图片(称之为媒体内容)，其中一个可以是视频或 gif，...，更改我现有的 API 将意味着更改返回类型。客户端必须分析返回的 JSON 以确定它正在处理的内容类型等。

我知道这是一个相当笼统的问题，可能没有正确答案，但在我下定决心之前，我很想听听一些意见。

Answer 1

答案是:视情况而定。基本上你应该提供单独的端点，遵循 SRP - 它也适用于 REST 设计。

另外请注意，应用程序无论如何都会进行多次调用 - 每张图片都将单独下载。

与应用程序交互的客户端类型也很重要 - 移动或网络/桌面。在移动交互的情况下，最好在尽可能少的请求中提供所有必要的信息 - 您可以节省宽带 - 而且它通常工作得更快。

在这种特殊情况下，您还可以使用一种资源查询语言 - RQL .它将按如下方式工作:

GET /pictures/

返回基本信息:例如ID 和 pictureURL。

GET /pictures/{ID}

返回关于图片的全部可用数据。这是你已经定义的。这个想法是以这样一种方式扩展第一个端点，它将返回通过 fields 查询参数传递的所有字段。

GET /pictures/?fields=pictureURL,ID,tags

这样，您就有了一个用于返回所有图像的快速端点，一个用于返回图像详细信息的单独端点，并且如果消费者希望最大限度地减少调用次数，您还可以提供灵活的 API。

附言请从 URL 中删除版本控制 - header 对于版本控制要好得多。