一些基于rest的服务使用不同的资源uri进行更新/获取/删除和创建。如
Create -在某些地方使用/resource(单数)使用POST方法使用/resources(复数) 更新-使用PUT方法使用/resource/123 Get -使用Get方法使用/resource/123
我对这个URI命名约定有点困惑。我们应该用复数还是单数来创建资源?决定的标准应该是什么?
一些基于rest的服务使用不同的资源uri进行更新/获取/删除和创建。如
Create -在某些地方使用/resource(单数)使用POST方法使用/resources(复数) 更新-使用PUT方法使用/resource/123 Get -使用Get方法使用/resource/123
我对这个URI命名约定有点困惑。我们应该用复数还是单数来创建资源?决定的标准应该是什么?
当前回答
保持一致就好。
使用任何一个单数:
POST /resource
PUT /resource/123
GET /resource/123
或复数:
POST /resources
PUT /resources/123
GET /resources/123
其他回答
对我来说,最好有一个模式,你可以直接映射到代码(容易自动化),主要是因为代码是什么将在两端。
GET /orders <---> orders
POST /orders <---> orders.push(data)
GET /orders/1 <---> orders[1]
PUT /orders/1 <---> orders[1] = data
GET /orders/1/lines <---> orders[1].lines
POST /orders/1/lines <---> orders[1].lines.push(data)
复数
简单-所有url都以相同的前缀开头 逻辑——订单/获取订单的索引列表。 标准——被绝大多数公共和私有api广泛采用的标准。
例如:
GET /resources -返回资源项的列表
POST /resources -创建一个或多个资源项
PUT /resources—更新一个或多个资源项
PATCH /resources—部分更新一个或多个资源项
DELETE /resources -删除所有资源项
对于单个资源项:
GET /resources/:id -根据:id参数返回一个特定的资源项
POST /resources/:id—用指定的id创建一个资源项(需要验证)
PUT /resources/:id -更新一个特定的资源项
PATCH /resources/:id—部分更新特定的资源项
DELETE /resources/:id -删除指定的资源项
对于单数的提倡者,可以这样想:你会向某人要一份订单,并期待一件事,还是一份清单?那么,当您键入/订单时,为什么期望服务返回一列东西呢?
以下是Roy Fielding关于“基于网络的软件架构的架构风格和设计”的论文,这句话你可能会感兴趣:
资源是概念上的映射 到一组实体,而不是与中任何特定点的映射对应的实体 时间。
作为一个资源,映射到一组实体,对我来说,使用/product/作为访问一组产品的资源,而不是/products/本身,似乎不符合逻辑。如果需要特定的产品,则访问/products/1/。
作为进一步的参考,这个来源有一些关于资源命名约定的单词和例子:
https://restfulapi.net/resource-naming/
最重要的事情
当你在接口和代码中使用复数时,问问你自己,你的约定是如何处理这些词的:
/pants, /eye-glasses——是单数还是复数? /radii -你知道它的唯一路径是/radius还是/radix吗? /index -你知道它的复数路径是/indexes或/indexes或/indexes吗?
理想情况下,约定的规模应该没有不规则性。英语复数就不会这样,因为
它们也有例外,比如某物被称为复数形式,以及 没有简单的算法可以从一个词的单数中得到一个词的复数,从复数中得到一个词的单数,或者判断一个未知名词是单数还是复数。
这也有缺点。我脑海中最突出的是:
The nouns whose singular and plural forms are the same will force your code to handle the case where the "plural" endpoint and the "singular" endpoint have the same path anyway. Your users/developers have to be proficient with English enough to know the correct singulars and plurals for nouns. In an increasingly internationalized world, this can cause non-negligible frustration and overhead. It singlehandedly turns "I know /foo/{{id}}, what's the path to get all foo?" into a natural language problem instead of a "just drop the last path part" problem.
与此同时,一些人类语言甚至没有名词的单数形式和复数形式。他们还行。你的API也可以。
单数
方便 事物可以有不规则的复数名称。有时他们没有。 但是单数的名字总是存在的。
例如,CustomerAddress over CustomerAddresses
考虑这个相关的资源。
/order/12/orderdetail/12比/orders/12/orderdetails/4更具可读性和逻辑性。
数据库表
资源表示像数据库表这样的实体。 它应该有一个逻辑上的单数名称。 这是关于表名的答案。
类映射
类总是单数的。ORM工具生成的表与类名相同。随着越来越多的工具被使用,单数名称正成为一种标准。
阅读更多关于REST API开发者的困境
对于没有单一名称的事物
在裤子和太阳镜的例子中,它们似乎没有一个单一的对应。他们是众所周知的,他们似乎是单数的使用。就像一双鞋。考虑将类文件命名为Shoe或Shoes。在这里,这些名称的使用必须被视为一个单一的实体。你不会看到任何人买了一只鞋就把URL设为
/shoe/23
我们必须把鞋子看做一个单一的实体。
参考:Top 6 REST命名最佳实践