我想让我的RESTful API非常可预测。决定何时使用URI而不是使用查询参数分割数据的最佳实践是什么?
对我来说,支持分页、排序和分组的系统参数在'?'之后是有意义的。但是,像“status”和“region”这样的字段或其他属性如何划分您的集合呢?如果这些是查询参数,什么是关于知道什么时候使用路径参数的经验法则?
我想让我的RESTful API非常可预测。决定何时使用URI而不是使用查询参数分割数据的最佳实践是什么?
对我来说,支持分页、排序和分组的系统参数在'?'之后是有意义的。但是,像“status”和“region”这样的字段或其他属性如何划分您的集合呢?如果这些是查询参数,什么是关于知道什么时候使用路径参数的经验法则?
当前回答
TL;DR: RESTful API设计的最佳实践是,路径参数用于标识一个或多个特定资源,而查询参数用于对这些资源进行排序/筛选。
举个例子。假设您正在为一个名为Car的实体实现RESTful API端点。你可以这样构造端点:
GET /汽车 得到/汽车/:id POST /汽车 /汽车/:id 删除/汽车/:id
这样,在指定要获取的资源时只使用路径参数,但不会以任何方式对资源进行排序/筛选。
现在假设您希望在GET请求中添加按颜色过滤汽车的功能。因为颜色不是资源(它是资源的属性),所以可以添加一个查询参数来执行此操作。你可以像这样将查询参数添加到GET /cars请求中:
获取/汽车?颜色=蓝色
这个端点将被实现,以便只返回蓝色的汽车。
我们可以使用&符号添加更多的过滤参数:
GET /cars?color=blue&brand=ferrari
就语法而言,URL名应该全部小写。如果实体名称通常由两个英文单词组成,则应该使用连字符分隔单词,而不是驼峰大小写。
例/两个词
其他回答
在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名应该全部小写。如果实体名称通常由两个英文单词组成,则应该使用连字符分隔单词,而不是驼峰大小写。
例/两个词
一般来说,当资源中存在明显的“层次结构”时,我倾向于使用路径参数,例如:
/region/state/42
如果该单一资源具有状态,则可以:
/region/state/42/status
但是,如果‘region’实际上不是所公开的资源的一部分,它可能属于查询参数之一——类似于分页(如您所提到的)。
示例URL: /rest/{keyword}
该URL是路径参数的示例。我们可以使用@PathParam来获取这个URL数据。
示例URL: /rest?关键词= java&limit = 10
该URL是查询参数的示例。我们可以使用@Queryparam来获取这个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
希望这有意义。