一些基于rest的服务使用不同的资源uri进行更新/获取/删除和创建。如

Create -在某些地方使用/resource(单数)使用POST方法使用/resources(复数) 更新-使用PUT方法使用/resource/123 Get -使用Get方法使用/resource/123

我对这个URI命名约定有点困惑。我们应该用复数还是单数来创建资源?决定的标准应该是什么?


当前回答

为了简单和一致性,我更喜欢使用单数形式。

例如,考虑以下url:

/客户/ 1

我将把客户视为客户集合,但是为了简单起见,集合部分被删除了。

另一个例子:

/设备/ 1

在这种情况下,equipment不是正确的复数形式。因此,为了简单起见,将其视为设备集合和删除集合,使其与客户案例一致。

其他回答

在所有方法中使用复数至少在一个方面更实用: 如果你正在使用Postman(或类似的工具)开发和测试资源API,当从GET切换到PUT再切换到POST时,你不需要编辑URI。

单数

方便 事物可以有不规则的复数名称。有时他们没有。 但是单数的名字总是存在的。

例如,CustomerAddress over CustomerAddresses

考虑这个相关的资源。

/order/12/orderdetail/12比/orders/12/orderdetails/4更具可读性和逻辑性。

数据库表

资源表示像数据库表这样的实体。 它应该有一个逻辑上的单数名称。 这是关于表名的答案。

类映射

类总是单数的。ORM工具生成的表与类名相同。随着越来越多的工具被使用,单数名称正成为一种标准。

阅读更多关于REST API开发者的困境

对于没有单一名称的事物

在裤子和太阳镜的例子中,它们似乎没有一个单一的对应。他们是众所周知的,他们似乎是单数的使用。就像一双鞋。考虑将类文件命名为Shoe或Shoes。在这里,这些名称的使用必须被视为一个单一的实体。你不会看到任何人买了一只鞋就把URL设为

/shoe/23

我们必须把鞋子看做一个单一的实体。

参考:Top 6 REST命名最佳实践

从API使用者的角度来看,端点应该是可预测的

在理想的情况下……

GET /resources should return a list of resources. GET /resource should return a 400 level status code. GET /resources/id/{resourceId} should return a collection with one resource. GET /resource/id/{resourceId} should return a resource object. POST /resources should batch create resources. POST /resource should create a resource. PUT /resource should update a resource object. PATCH /resource should update a resource by posting only the changed attributes. PATCH /resources should batch update resources posting only the changed attributes. DELETE /resources should delete all resources; just kidding: 400 status code DELETE /resource/id/{resourceId}

这种方法最灵活,功能最丰富,但开发起来也最耗时。因此,如果您很着急(软件开发总是这样),只需命名您的端点资源或复数形式的资源。我更喜欢单数形式,因为它让你可以选择内省和编程计算,因为不是所有的复数形式都以's'结尾。

说了这么多,不管出于什么原因,最常用的实践开发人员选择使用复数形式。这是我最终选择的路线,如果你看看流行的api,如github和twitter,这就是他们所做的。

决定的一些标准可以是:

我的时间限制是什么? 我将允许我的消费者做哪些操作? 请求和结果有效负载是什么样子的? 我是否希望能够在代码中使用反射并解析URI ?

所以这取决于你。无论你做什么都要坚持。

对于命名惯例,通常可以安全地说“只选择一个并坚持使用它”,这是有道理的。

然而,在不得不向许多人解释REST之后,将端点表示为文件系统上的路径是最具表现力的方法。 它是无状态的(文件存在或不存在),分层的,简单的,熟悉的-您已经知道如何访问静态文件,无论是本地还是通过http。

在这种情况下,语言规则只能让你达到以下效果:

一个目录可以包含多个文件和/或子目录,因此它的名称应该是复数形式。

但我喜欢妳 不过,另一方面,这是您的目录,如果您愿意,您可以将其命名为“一个资源或多个资源”。这不是真正重要的事情。

重要的是,如果您将一个名为“123”的文件放在名为“resourceS”的目录下(结果是/resourceS/123),那么您就不能期望通过/resource/123访问它。

不要试图让它变得比原来更聪明——根据你当前访问的资源数量从复数变成单数对某些人来说可能是美观的,但这并不是有效的,在一个等级系统中也没有意义。

注意:技术上,你可以创建“符号链接”,这样/resources/123也可以通过/resource/123访问,但前者仍然必须存在!

我知道大多数人都在犹豫是用复数还是单数。这里没有解决的问题是,客户需要知道您使用的是哪一个,而且他们总是有可能犯错误。这就是我的建议的来源。

两者都怎么样?我的意思是,在整个API中使用单数形式,然后创建路由,将复数形式的请求转发到单数形式。例如:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

你懂的。没有人是错的,最小的努力,客户总是会得到正确的。