API 的 URL 设计 [英] URL design for an API
问题描述
我正在为我们的后端开发私有 API.
我的收藏有关联.
可以对每个集合进行请求、分页，也可以请求关联并对这些关联进行分页.
I'm working on a private apis for our backend.
I have collections that have associations.
Each collection can be requested, paginated, you can also ask for the associations and paginate this associations.
我们不确定要使用哪种 URL 设计……我们正在考虑:
We're not sure about which URL design to use ... we're thinking about :
/users.json?per_page=10&association=parts,auditions&parts_per_page=5&auditions_per_page=5
/users.json?per_page=10&association=parts,auditions&parts_per_page=5&auditions_per_page=5
/users.json?per_page=10&association[]=parts&association[]=auditions&parts_per_page=5&auditions_per_page=10
/users.json?per_page=10&association[]=parts&association[]=auditions&parts_per_page=5&auditions_per_page=10
/users.json?per_page=10&association[auditions]=true&association[parts][per_page]=5
/users.json?per_page=10&association[auditions]=true&association[parts][per_page]=5
你怎么看?你会选择哪一个?为什么 ?其中之一看起来不像有效的 url 方案吗?
What do you think ? which one would you chosse ? why ? is one of this not looking like valid url schemes ?
谢谢！
推荐答案
我的答案:/users.json.HTTP 针对大粒度超媒体传输进行了优化；缓存是其中的一个重要部分，上面给出的 URI 方案都不是非常适合缓存的.
My answer: /users.json. HTTP is optimized for large-grain hypermedia transfer; caching is a big part of this, and none of the URI schemes given above are very cache-friendly.
例如，Squid 是一种流行的 HTTP 缓存，默认情况下不会缓存任何具有查询字符串的 URL.此外，许多客户端甚至服务器和中介以未定义的顺序生成和使用查询字符串参数；即，?a=3&b=5"可以任意改写为?b=5&a=3".但是，对于 HTTP 缓存，顺序很重要，即使两个页面具有相同的内容，它们也会被单独缓存.随着您添加参数，此问题呈指数级增长.
您应该设计您的资源(及其表示)，以通过两种相反但互补的技术利用缓存:
You should design your resources (and their representations) to take advantage of caching by two opposing but complementary techniques:
- 将碎片化和部分表示组合成更大、统一的表示，以及
- 沿缓存边界(往往是事务边界)将大型统一表示分离为较小的表示，但通过超链接相关联.
在您的情况下，第 1 步意味着将关联和部分组合到用户"表示中，客户端没有任何选项来配置哪些和多少.这将允许您主动缓存单个响应表示，而不会因所有查询字符串选项而使您(及其)缓存过载.
In your case, step 1 implies combining associations and parts into the "users" representation, without any option for the client to configure which ones and how many. That will allow you to aggressively cache the single response representation without overloading your (and their) caches with a combinatorial explosion of responses due to all the querystring options.
第 2 步意味着将 /users.json 分成单独的用户"实体，每个实体都有一个关联"资源和一个部分"资源.所以 /users/{id} 和 /users/{id}/associations 和 /users/{id}/parts./users"资源然后返回一个指向各个/users/{id}"资源的超链接数组，每个/users/{id}"表示都包含指向其关联和部分的超链接(该部分更具延展性——- 将关联和部分直接嵌入到用户资源中可能更适合您的应用程序.这将允许您主动缓存每个按需"资源的响应，而无需缓存整个数据库.
Step 2 implies separating /users.json into separate "user" entities, each with an "associations" resource and a "parts" resource. So /users/{id} and /users/{id}/associations and /users/{id}/parts. The "/users" resource then returns an array of hyperlinks to the individual "/users/{id}" resources, and each "/users/{id}` representation contains hyperlinks to its associations and parts (that part is more malleable--it might fit your application better to embed the associations and parts into the user resource directly). That will allow you to aggressively cache the response for each "in demand" resource without having to cache your whole database.
然后您的用户会尖叫但这是网络流量的 10 倍！"对此，您冷静地回答:不，那是网络流量的 1/10，因为 10 次请求的资源中有 9 次已经位于您的客户端(浏览器)缓存中(如果不是，则为 1/10)服务器的计算资源，因为它们位于服务器端缓存中，当它们也不存在时，我们避免在服务器上使用智能缓存进行标记)."
Then your users will scream "but that's 10 times the network traffic!" To which you calmly respond, "no, that's 1/10th the network traffic, because 9 times out of 10 the requested resources are already sitting in your client-side (browser) cache (and when they're not, it's 1/10th the server's computational resources since they're sitting in a server-side cache, and when they're not there either, we avoid stampeding with a smart cache on the server)."
当然，如果 /users 资源是每天有 100 万新访问者访问的资源，那么您的优化路径可能会有所不同.但根据您的示例 URI 方案，它似乎并非如此.
Of course, if the /users resource is something a million new visitors hit every day, then your optimization path might be different. But it doesn't seem so based on your example URI schemes.
这篇关于API 的 URL 设计的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
