API的URL设计

Question

我正在为我们的后端工作私人api.
我的馆藏有关联.
每个集合都可以请求,分页,您也可以请求关联并对这些关联进行分页.

我们不确定要使用哪种网址设计...我们正在考虑:

• /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

你怎么看 ？你会选择哪一个？为什么？其中一个看起来不像有效的网址方案？

谢谢 !

Answer 1

我的回答:/users.json.HTTP针对大粒度超媒体传输进行了优化; 缓存是其中很重要的一部分,上面给出的URI方案都不是缓存友好的.

例如,Squid是一种流行的HTTP缓存,默认情况下不会缓存任何具有查询字符串的URL.此外,许多客户端甚至服务器和中介以未定义的顺序生成和使用查询字符串参数; 也就是说,"？a = 3&b = 5"可以任意改写为"？b = 5&a = 3".但是,对于HTTP缓存,顺序很重要,即使它们具有相同的内容,这两个页面也将单独缓存.添加参数时,此问题会呈指数级增长.

您应该设计您的资源(及其表示),以利用两种相反但互补的技术进行缓存:

1. 将碎片和部分表示组合成更大的统一表示,以及
2. 将大的统一表示分成沿缓存边界(通常是事务边界)的较小表示,但是通过超链接相关联.

在您的情况下,步骤1意味着将关联和部分组合到"用户"表示中,而没有任何选项供客户端配置哪些和多少.这将允许您积极地缓存单个响应表示,而不会因为所有查询字符串选项而导致响应的组合爆炸超载您的(及其)缓存.

步骤2意味着分离/users.json成单独的"用户"实体,每个实体具有"关联"资源和"部分"资源.因此,/users/{id}与/users/{id}/associations和/users/{id}/parts.然后,"/ users"资源返回指向各个"/ users/{id}"资源的超链接数组,每个"/ users/{id}"表示包含指向其关联和部分的超链接(该部分更具延展性 - -it可能更适合您的应用程序,直接将关联和部分嵌入到用户资源中.这将允许您积极地缓存每个"按需"资源的响应,而无需缓存整个数据库.

然后你的用户会尖叫"但这是网络流量的10倍!" 你冷静地回答,"不,这是网络流量的十分之一,因为所需资源中的9个已经位于客户端(浏览器)缓存中(当它们不在时,它是1/10服务器的计算资源,因为它们位于服务器端缓存中,当它们不存在时,我们避免在服务器上加盖智能缓存."

当然,如果/users资源是每天有数百万新访问者,那么您的优化路径可能会有所不同.但它似乎不是基于您的示例URI方案.