API的URL设计

Question

我正在为我们的后端使用私人API。
我有拥有关联的集合。
每个集合都可以请求分页，也可以请求关联并对这些关联进行分页。

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

• /users.json?per_page=10 &协会=零件，试镜& parts_per_page = 5 & auditions_per_page = 5

• /users.json?per_page=10 &关联[] =份&关联[] =试镜& parts_per_page = 5 & auditions_per_page = 10

• /users.json?per_page=10 &协会[试听] =真&协会[零件] [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}”表示包含到其关联和部分的超链接（该部分更具可塑性 - - 它可能会更好地将您的应用程序嵌入到用户资源中直接嵌入到用户资源中），这将允许您积极缓存每个“需求”资源的响应，而不必缓存整个数据库。用户会尖叫“但是这是网络流量的10倍！”对此你冷静地回应，“不，这是网络流量的1/10，因为10次请求的资源中有9次已经位于客户端（浏览器）缓存（当它们不存在时，它是服务器计算资源的十分之一，因为它们坐在服务器端缓存中，并且当它们不在那里时，我们避免了令人讨厌的机智h服务器上的智能缓存）。“

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

Answer 2

restful-url标签下有很多有用的帖子。

一些有用的帖子：

Do REST API URLs have to look like this?

Best practices on using URIs as parameter value in REST calls.

How to create REST URL's without verbs?

Answer 3

我会去的第一个1。我不喜欢在URL上看到[]符号，恕我直言，它使客户更难以使用和理解。建议的一些变化。

1）作为联想似乎是一个数组，变更为协会（复数，如果我是正确的，它是一个数组）

2）您也可以尝试把默认per_page和一个可选的一个，甚至是聚合，就像per_page_parts_auditions，而不是同时使用per_page_parts和per_page_auditions。我不会这样做，如果你的API被设计为公开的，因为它更容易使用但更难理解，但是因为你发布它是私有的。应该是避免复制的好方法。