我目前正在尝试实现一个 API,该 API 将为我的客户提供内容,但我不确定如何为此正确设计我的 API。特别是我的问题是:
以客户端发出多个请求为代价,让特定的 API 为特定场景提供服务更好,还是拥有一个服务于所有可能值的全能 API 更好,以最大限度地减少客户端必须发出的请求。
例如,在列出带有描述/标题/标签/等的图片的应用程序中,将有两种情况:
第 1 页:
现在我可以通过两种方式设计它:
(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"
}
显然,在第一个变体中,客户端只需要执行 1 个请求。使用 X 图片和 Y 属性,这将是一个相当大的 JSON 响应,但是客户端不需要查询任何显示附加信息的附加信息。
在这些场景中是否有指南或最佳实践?
我个人更喜欢场景 2,因为它使 API 更具体,服务器开发更容易(想象多个表、多个连接以获取所有信息)。此外,感觉 API 不太容易改变,因为每个方法都是特定的并返回正确的内容。
例如:
如果我决定添加不同类型的图片(称为媒体内容),其中一个可以是视频或 gif,...,更改我现有的 API 将意味着更改返回类型。客户端必须分析返回的 JSON 以确定它正在处理的内容类型等。
我知道这是一个相当笼统的问题,可能没有正确的答案,但在我下定决心之前,我很想听听一些意见。
最佳答案
答案是:视情况而定。基本上,您应该在 SRP 之后提供单独的端点 - 它也适用于 REST 设计。
还要注意应用程序无论如何都会进行多次调用的事实 - 每个图像都将单独下载。
什么样的客户端与应用程序交互也很重要——移动或网络/桌面。在移动交互的情况下,最好在尽可能少的请求中提供所有必要的信息——你节省了宽带——而且它通常工作得更快。
在这种特殊情况下,您还可以使用一种资源查询语言 - RQL 。它将按如下方式工作:
GET /pictures/
返回基本信息:例如
ID
和 pictureURL
。GET /pictures/{ID}
返回有关图片的全部可用数据。这是你已经定义的。这个想法是以这样一种方式扩展第一个端点,它将返回通过
fields
查询参数传递的所有字段。GET /pictures/?fields=pictureURL,ID,tags
通过这种方式,您有一个用于返回所有图像的快速端点,一个用于返回图像详细信息的单独端点,并且如果消费者希望最大限度地减少调用次数,您可以提供灵活的 API。
附言请从 URL 中删除版本控制 - 标题对于版本控制要好得多。
关于json - 服务器客户端应用程序的 API 设计,我们在Stack Overflow上找到一个类似的问题:https://stackoverflow.com/questions/33371787/