一些基于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命名约定有点困惑。我们应该用复数还是单数来创建资源?决定的标准应该是什么?
当前回答
单数
方便 事物可以有不规则的复数名称。有时他们没有。 但是单数的名字总是存在的。
例如,CustomerAddress over CustomerAddresses
考虑这个相关的资源。
/order/12/orderdetail/12比/orders/12/orderdetails/4更具可读性和逻辑性。
数据库表
资源表示像数据库表这样的实体。 它应该有一个逻辑上的单数名称。 这是关于表名的答案。
类映射
类总是单数的。ORM工具生成的表与类名相同。随着越来越多的工具被使用,单数名称正成为一种标准。
阅读更多关于REST API开发者的困境
对于没有单一名称的事物
在裤子和太阳镜的例子中,它们似乎没有一个单一的对应。他们是众所周知的,他们似乎是单数的使用。就像一双鞋。考虑将类文件命名为Shoe或Shoes。在这里,这些名称的使用必须被视为一个单一的实体。你不会看到任何人买了一只鞋就把URL设为
/shoe/23
我们必须把鞋子看做一个单一的实体。
参考:Top 6 REST命名最佳实践
其他回答
对我来说,最好有一个模式,你可以直接映射到代码(容易自动化),主要是因为代码是什么将在两端。
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)
对于命名惯例,通常可以安全地说“只选择一个并坚持使用它”,这是有道理的。
然而,在不得不向许多人解释REST之后,将端点表示为文件系统上的路径是最具表现力的方法。 它是无状态的(文件存在或不存在),分层的,简单的,熟悉的-您已经知道如何访问静态文件,无论是本地还是通过http。
在这种情况下,语言规则只能让你达到以下效果:
一个目录可以包含多个文件和/或子目录,因此它的名称应该是复数形式。
但我喜欢妳 不过,另一方面,这是您的目录,如果您愿意,您可以将其命名为“一个资源或多个资源”。这不是真正重要的事情。
重要的是,如果您将一个名为“123”的文件放在名为“resourceS”的目录下(结果是/resourceS/123),那么您就不能期望通过/resource/123访问它。
不要试图让它变得比原来更聪明——根据你当前访问的资源数量从复数变成单数对某些人来说可能是美观的,但这并不是有效的,在一个等级系统中也没有意义。
注意:技术上,你可以创建“符号链接”,这样/resources/123也可以通过/resource/123访问,但前者仍然必须存在!
以下是Roy Fielding关于“基于网络的软件架构的架构风格和设计”的论文,这句话你可能会感兴趣:
资源是概念上的映射 到一组实体,而不是与中任何特定点的映射对应的实体 时间。
作为一个资源,映射到一组实体,对我来说,使用/product/作为访问一组产品的资源,而不是/products/本身,似乎不符合逻辑。如果需要特定的产品,则访问/products/1/。
作为进一步的参考,这个来源有一些关于资源命名约定的单词和例子:
https://restfulapi.net/resource-naming/
使用/resources的前提是它表示“所有”资源。如果执行GET /resources,则可能返回整个集合。通过发布到/resources,您将添加到集合中。
但是,单个资源在/resource上可用。如果执行GET /resource请求,则可能会出错,因为这个请求没有任何意义,而/resource/123则完全有意义。
使用/resource而不是/resources类似于使用文件系统和文件集合,/resource是包含单独的123,456个文件的“目录”。
没有对错之分,你喜欢什么就去做什么。
最重要的事情
当你在接口和代码中使用复数时,问问你自己,你的约定是如何处理这些词的:
/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也可以。