一些基于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命名约定有点困惑。我们应该用复数还是单数来创建资源?决定的标准应该是什么?
当前回答
使用/resources的前提是它表示“所有”资源。如果执行GET /resources,则可能返回整个集合。通过发布到/resources,您将添加到集合中。
但是,单个资源在/resource上可用。如果执行GET /resource请求,则可能会出错,因为这个请求没有任何意义,而/resource/123则完全有意义。
使用/resource而不是/resources类似于使用文件系统和文件集合,/resource是包含单独的123,456个文件的“目录”。
没有对错之分,你喜欢什么就去做什么。
其他回答
复数
简单-所有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 -删除指定的资源项
对于单数的提倡者,可以这样想:你会向某人要一份订单,并期待一件事,还是一份清单?那么,当您键入/订单时,为什么期望服务返回一列东西呢?
对于命名惯例,通常可以安全地说“只选择一个并坚持使用它”,这是有道理的。
然而,在不得不向许多人解释REST之后,将端点表示为文件系统上的路径是最具表现力的方法。 它是无状态的(文件存在或不存在),分层的,简单的,熟悉的-您已经知道如何访问静态文件,无论是本地还是通过http。
在这种情况下,语言规则只能让你达到以下效果:
一个目录可以包含多个文件和/或子目录,因此它的名称应该是复数形式。
但我喜欢妳 不过,另一方面,这是您的目录,如果您愿意,您可以将其命名为“一个资源或多个资源”。这不是真正重要的事情。
重要的是,如果您将一个名为“123”的文件放在名为“resourceS”的目录下(结果是/resourceS/123),那么您就不能期望通过/resource/123访问它。
不要试图让它变得比原来更聪明——根据你当前访问的资源数量从复数变成单数对某些人来说可能是美观的,但这并不是有效的,在一个等级系统中也没有意义。
注意:技术上,你可以创建“符号链接”,这样/resources/123也可以通过/resource/123访问,但前者仍然必须存在!
以下是Roy Fielding关于“基于网络的软件架构的架构风格和设计”的论文,这句话你可能会感兴趣:
资源是概念上的映射 到一组实体,而不是与中任何特定点的映射对应的实体 时间。
作为一个资源,映射到一组实体,对我来说,使用/product/作为访问一组产品的资源,而不是/products/本身,似乎不符合逻辑。如果需要特定的产品,则访问/products/1/。
作为进一步的参考,这个来源有一些关于资源命名约定的单词和例子:
https://restfulapi.net/resource-naming/
保持一致就好。
使用任何一个单数:
POST /resource
PUT /resource/123
GET /resource/123
或复数:
POST /resources
PUT /resources/123
GET /resources/123
我知道大多数人都在犹豫是用复数还是单数。这里没有解决的问题是,客户需要知道您使用的是哪一个,而且他们总是有可能犯错误。这就是我的建议的来源。
两者都怎么样?我的意思是,在整个API中使用单数形式,然后创建路由,将复数形式的请求转发到单数形式。例如:
GET /resources = GET /resource
GET /resources/1 = GET /resource/1
POST /resources/1 = POST /resource/1
...
你懂的。没有人是错的,最小的努力,客户总是会得到正确的。