REST URI约定 - 创建资源时的单数或复数名称

Question

我是REST的新手,我发现在一些RESTful服务中,他们使用不同的资源URI进行更新/获取/删除和创建.如

• 创建 - 使用/ resource(单数)在某些地方使用POST方法(观察复数)使用/ resources
• 更新 - 使用/ resource/123和PUT方法
• 获取 - 使用/ resource/123和GET方法

我对这个URI命名约定有点困惑.我们应该使用复数或单数来创建资源？决定时应该有什么标准？

Answer 1

对我来说最好有一个可以直接映射到代码的模式(易于自动化),主要是因为代码是两端的.

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) 

Answer 2

使用的前提/resources是它代表"所有"资源.如果您这样做GET /resources,您可能会返回整个集合.通过POST /resources,您将添加到集合中.

但是,个人资源可在/ resource获得.如果你这样做GET /resource,你可能会出错,因为这个请求没有任何意义,但是很/resource/123有道理.

使用/resource,而不是/resources类似于你会怎么做,如果你用,比如工作,文件系统和文件的集合,/resource是"目录"与个人123,456在它的文件.

无论哪种方式都是对或错,请选择您最喜欢的方式.

Answer 3

我也没有看到这样做的重点,我认为这不是最好的URI设计.作为RESTful服务的用户,我希望列表资源具有相同的名称,无论我是否访问列表中的列表或特定资源.无论您是要使用列表资源还是特定资源,都应使用相同的标识符.

Answer 4

复数

• 简单 - 所有网址都以相同的前缀开头
• 逻辑 - orders/获取订单的索引列表.
• 标准 - 最广泛采用的标准,其次是绝大多数公共和私有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 - 删除特定资源项

对于单数的拥护者,可以这样想:你会问一个人order并且期待一件事或一系列事情吗？那么,为什么您希望服务在您键入时返回一个列表/order？

Answer 5

单数

便利 事物可以有不规则的复数名称.有时他们没有.但奇异的名字总是在那里.

例如CustomerAddresses上的CustomerAddress

考虑这个相关的资源.

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

数据库表

资源表示像数据库表这样的实体.它应该具有逻辑上的单数名称.这是表名的答案.

类映射

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

阅读有关REST API Developer's Dilemma的更多信息

Answer 6

虽然最普遍的做法是RESTful apis,其中使用复数,例如/api/resources/123,有一个特殊情况,我发现使用比复数名称更恰当/富有表现力的单数名称.这是一对一关系的情况.特别是如果目标项是值对象(在Domain-driven-design范例中).

让我们假设每个资源都是一对一的accessLog,可以将其建模为值对象,即不是实体,因此没有ID.它可以表达为/api/resources/123/accessLog.通常的动词(POST,PUT,DELETE,GET)将恰当地表达意图以及这种关系确实是一对一的事实.

Answer 7

为什么不遵循数据库表名的普遍趋势,通常接受单数形式？在那里,完成了 - 让我们重用.

表命名困境:奇异与多个名称

Answer 8

我很惊讶地看到很多人会跳上复数名词的潮流.在实现单数转换为多数转换时,您是否正在处理不规则复数名词？你喜欢疼吗？

见 http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

有许多类型的不规则复数,但这些是最常见的:

名词类型形成复数的例子

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

Answer 9

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

理想的情况下...

1. GET /resources 应该返回资源列表.
2. GET /resource 应返回400级状态代码.
3. GET /resources/id/{resourceId} 应该返回一个包含一个资源的集合.
4. GET /resource/id/{resourceId} 应该返回一个资源对象.
5. POST /resources 应该批量创建资源.
6. POST /resource 应该创建一个资源.
7. PUT /resource 应该更新资源对象.
8. PATCH /resource 应该通过仅发布更改的属性来更新资源.
9. PATCH /resources 应该批量更新仅发布已更改属性的资源.
10. DELETE /resources应删除所有资源; 开玩笑:400状态代码
11. DELETE /resource/id/{resourceId}

这种方法最灵活,功能最丰富,但也是最耗时的开发方法.因此,如果您赶时间(软件开发总是这样),只需命名您的端点resource或复数形式resources.我更喜欢单数形式,因为它为您提供了以编程方式进行内省和评估的选项,因为并非所有复数形式都以's'结尾.

说了这么多,无论出于何种原因,最常用的练习开发者选择的是使用复数形式.这是最终我选择的路线,如果你看流行的API,如github和twitter,这是他们做什么.

决定的一些标准可能是:

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

所以这取决于你.无论你做什么都是一致的.

Answer 10

路由中的 id 应该被视为与列表的索引相同，并且命名应该相应地进行。

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

但是有些资源在它们的路由中不使用 id，因为要么只有一个，要么用户永远无法访问多个，所以这些不是列表：

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

Answer 11

最重要的事情

每当您在界面和代码中使用复数时，问问自己，您的惯例如何处理这样的单词：

• /pants, /eye-glasses- 这些是单数路径还是复数路径？

• /radii- 你是否立刻就知道该路径的唯一路径是/radiusor /radix？

• /index- 你是否立即知道复数路径是否是/indexesor/indeces或/indices？

理想情况下，约定应该能够无规则地扩展。英语复数形式不会这样做，因为

1. 它们有例外，例如以复数形式调用的某物之一，并且
2. 没有简单的算法可以从单数得到单词的复数，从复数得到单数，或者判断未知名词是单数还是复数。

这有缺点。我脑海中最突出的几个：

1. 单数和复数形式相同的名词将强制您的代码处理“复数”端点和“单数”端点具有相同路径的情况。
2. 您的用户/开发人员必须精通英语，才能知道名词的正确单数和复数。在日益国际化的世界中，这可能会导致不可忽视的挫败感和开销。
3. 它单枪匹马地变成了“我知道了/foo/{{id}}，有什么办法可以得到一切foo呢？” 变成自然语言问题，而不是“只删除最后一个路径部分”问题。

与此同时，一些人类语言甚至没有不同的名词单数和复数形式。他们管理得很好。你的 API 也可以。

Answer 12

请参阅Google的API 设计指南：资源名称，了解另一种命名资源的方法。

该指南要求以复数形式命名集合。

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

如果您正在考虑这个主题，则值得一读。

Answer 13

我的两分钱：花费时间从复数变为单数或反之亦然的方法是浪费CPU周期。我可能是高中生，但是在我的时代，事物被称为相同。我如何查找有关人的方法？没有规律的表达不会覆盖人和人，而不会产生不良副作用。

英文复数可以是非常任意的，它们不必要地妨碍了代码。遵守一个命名约定。计算机语言应该是数学上的清晰度，而不是模仿自然语言。

Answer 14

我更喜欢使用单数形式来实现简单性和一致性.

例如,考虑以下网址:

/客户/ 1

我会将客户视为客户收集,但为简单起见,将删除收集部分.

另一个例子:

/设备/ 1

在这种情况下,设备不是正确的复数形式.因此,将其视为设备集合并简化集合,使其与客户案例保持一致.

Answer 15

我不喜欢看到{id}URL 的一部分与子资源重叠，因为id理论上可以是任何东西，并且会产生歧义。它混合了不同的概念（标识符和子资源名称）。

类似的问题经常出现在enum常量或文件夹结构中，其中不同的概念混合在一起（例如，当您有文件夹Tigers、Lions和Cheetahs，然后还有一个Animals在同一级别调用的文件夹时 - 这没有任何意义，因为其中一个是文件夹的子集）其他）。

一般来说，我认为端点的最后命名部分如果一次处理单个实体，则应该是单数；如果它处理实体列表，则应该是复数。

因此处理单个用户的端点：

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

然后有单独的资源用于对用户进行查询，通常返回一个列表：

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

这里有一些处理特定用户的子资源的示例：

GET /user/{id}/friends -> Returns a list of friends of given user

交个朋友（多对多链接）：

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

永远不会有任何歧义，资源的复数或单数命名是向用户暗示他们可以期望什么（列表或对象）。对 s 没有限制id，理论上可以让用户的 idnew不与（未来可能的）子资源名称重叠。