我想让我的RESTful API非常可预测。决定何时使用URI而不是使用查询参数分割数据的最佳实践是什么?

对我来说,支持分页、排序和分组的系统参数在'?'之后是有意义的。但是,像“status”和“region”这样的字段或其他属性如何划分您的集合呢?如果这些是查询参数,什么是关于知道什么时候使用路径参数的经验法则?


当前回答

有一次我设计了一个API,主要资源是人。通常用户会请求过滤过的人,以防止用户调用/people?每次我都执行了/people/urban,后来我可以轻松添加/people/rural。此外,这允许访问完整的/people列表,如果它以后有任何用处的话。简而言之,我的推理是为公共子集添加一个路径

从这里开始:

常见查询的别名 为了使API体验对普通消费者来说更愉快,可以考虑将一组条件打包到易于访问的RESTful路径中。例如,上面的最近关闭的门票查询可以打包为GET /tickets/recently_closed

其他回答

在REST API中,您不应该过度关注可预测的URI。URI可预测性暗示了对RESTful体系结构的误解。它假设客户端应该自己构造uri,实际上他们不应该这样做。

然而,我假设你不是在创建一个真正的REST API,而是一个“REST启发”的API(比如谷歌Drive)。在这些情况下,经验法则是“路径参数=资源标识”和“查询参数=资源排序”。所以,问题就变成了,你能在没有状态/区域的情况下唯一地识别你的资源吗?如果是,那么它可能是一个查询参数。如果不是,那么它是一个路径参数。

TL;DR: RESTful API设计的最佳实践是,路径参数用于标识一个或多个特定资源,而查询参数用于对这些资源进行排序/筛选。


举个例子。假设您正在为一个名为Car的实体实现RESTful API端点。你可以这样构造端点:

GET /汽车 得到/汽车/:id POST /汽车 /汽车/:id 删除/汽车/:id

这样,在指定要获取的资源时只使用路径参数,但不会以任何方式对资源进行排序/筛选。

现在假设您希望在GET请求中添加按颜色过滤汽车的功能。因为颜色不是资源(它是资源的属性),所以可以添加一个查询参数来执行此操作。你可以像这样将查询参数添加到GET /cars请求中:

获取/汽车?颜色=蓝色

这个端点将被实现,以便只返回蓝色的汽车。

我们可以使用&符号添加更多的过滤参数:

GET /cars?color=blue&brand=ferrari

就语法而言,URL名应该全部小写。如果实体名称通常由两个英文单词组成,则应该使用连字符分隔单词,而不是驼峰大小写。

例/两个词

细分更有层次,更“漂亮”,但可能会有限制。

例如,如果你有一个url,有三个段,每个段传递不同的参数,通过制造商,型号和颜色来搜索汽车:

www.example.com/search/honda/civic/blue

这是一个非常漂亮的url,更容易被最终用户记住,但现在你有点被这个结构困住了。假设你想让用户在搜索中搜索所有的蓝色汽车,或者所有的本田思域?查询参数可以解决这个问题,因为它给出了一个键值对。所以你可以通过:

www.example.com/search?color=blue
www.example.com/search?make=civic

现在,您可以通过键引用值——在查询代码中使用"color"或"make"。

你可以通过使用更多的段来创建一种键值结构来解决这个问题,比如:

www.example.com/search/make/honda/model/civic/color/blue

希望这有意义。

有一次我设计了一个API,主要资源是人。通常用户会请求过滤过的人,以防止用户调用/people?每次我都执行了/people/urban,后来我可以轻松添加/people/rural。此外,这允许访问完整的/people列表,如果它以后有任何用处的话。简而言之,我的推理是为公共子集添加一个路径

从这里开始:

常见查询的别名 为了使API体验对普通消费者来说更愉快,可以考虑将一组条件打包到易于访问的RESTful路径中。例如,上面的最近关闭的门票查询可以打包为GET /tickets/recently_closed

一般来说,当资源中存在明显的“层次结构”时,我倾向于使用路径参数,例如:

/region/state/42

如果该单一资源具有状态,则可以:

/region/state/42/status

但是,如果‘region’实际上不是所公开的资源的一部分,它可能属于查询参数之一——类似于分页(如您所提到的)。