URL设计的API [英] URL design for an API

问题描述

我工作在一个私人的API为我们的后端。结果
我有一个有关联的集合。结果
每个集合可要求，分页，你也可以要求协会和分页此关联。

我们是不知道要使用的URL设计......我们正在考虑：

• /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[auditions]=true&association[parts][per_page]=5

你觉得呢？你会chosse哪一个？为什么呢？就是这看起来不像有效的URL方案吗？

谢谢！

解决方案

我的回答： /users.json 。 HTTP是对于大粒超媒体传输进行了优化;缓存是这方面的一个重要组成部分，没有上面给出的URI方案都非常缓存友好。

的鱿鱼，例如，是一种流行的HTTP缓存，默认情况下将不缓存具有查询字符串的任何URL。此外，许多客户端和甚至服务器和中介产生并在未确定的订单消耗查询字符串参数;即？一个= 3和b = 5，可以任意地改写为B = 5和A = 3。然而，对于HTTP缓存，命令事项，以及两页将会分别缓存即使它们具有相同的内容。当您添加的参数，这个问题成倍增加。的

您必须由两人设计自己的资源（及重新presentations）利用高速缓存的对立而是相辅相成的技术：

1. 联合零散和局部重新presentations到更大的，统一的重presentations和


2. 独立的大，重新统一presentations成沿高速缓存边界重新较小presentations（这往往是事务边界），但由超有关。

在您的情况下，第1步意味着协会和零件组合成的用户重新presentation，无需客户端的任何选项来配置哪些和多少。这将允许您积极缓存重新presentation单应答，而不超载你（和他们）与缓存由于所有的查询字符串选择响应的组合爆炸。

步骤2意味着分离 /users.json 成单独的用户的实体，每个都有一个协会资源和部件的资源。因此， /用户/ {ID} 和 /用户/ {ID} /协会和 /用户/ {ID} /配件。那么/用户资源返回链接到个人/用户/（编号）资源的数组，每个/用户/ {ID}`再presentation包含超文本链接到它的协会和部分（即部分更可塑性 - 它可能适合你的应用程序更好地协会和部分直接嵌入到用户资源），将允许您积极缓存为每一个需求资源的响应，而无需你的缓存整个数据库

然后你的用户会尖叫但是这是网络流量的10倍！要你冷静地回答：不用，这是1/10的网络流量，因为9倍的10所请求的资源已经坐在你的客户端（浏览器）的缓存（当他们不是，它的1/10服务器的计算资源，因为他们坐在一个服务器端缓存，而当他们不存在要么，我们避免与服务器上的智能缓存）乱窜。

当然，如果 /用户的资源是什么一百万新的访问者每天都打，那么你的优化路径可能会有所不同。但它似乎不那么根据你的榜样URI方案。

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.

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&association[]=auditions&parts_per_page=5&auditions_per_page=10

• /users.json?per_page=10&association[auditions]=true&association[parts][per_page]=5

What do you think ? which one would you chosse ? why ? is one of this not looking like valid url schemes ?

Thanks !

解决方案

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, for example, is a popular HTTP cache that by default will not cache any URL that has a querystring. In addition, many clients and even servers and intermediaries generate and consume query string parameters in an undefined order; that is, "?a=3&b=5" can be arbitrarily rewritten as "?b=5&a=3". However, for HTTP caching, the order matters, and the two pages will be cached separately even though they have the same content. As you add parameters, this problem increases exponentially.

You should design your resources (and their representations) to take advantage of caching by two opposing but complementary techniques:

1. Combine fragmented and partial representations into larger, unified representations, and
2. Separate large, unified representations into smaller representations along cache boundaries (which tend to be transactional boundaries), but related by hyperlinks.

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.

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.

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)."

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.

这篇关于URL设计的API的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！