命名 RESTful 路径答案

【问题标题】：Naming RESTful paths命名 RESTful 路径
【发布时间】：2013-04-09 14:58:15
【问题描述】：

我正在创建一个 Web 服务，但我对路径名有一些疑问。如何在 RESTful Web 服务中指定对资源的操作？

例如：测验资源。您有正常的 CRUD 操作，并且您还想对测验做一些事情。比如生成一个新的测验。那是一个动作。你使用/quiz/top5 或/quiz?type=top5 之类的路径还是什么？

我不明白您在创建 RESTful 服务时如何编写对资源执行操作的路径。

【问题讨论】：

我会使用 /quiz/generate/123 作为 id 123
我会使用/quiz/{id}

标签： c# java web-services

【解决方案1】：

我会从apigee:Web API Design: Crafting Interfaces that Developers Love推荐这本电子书。

听从他们的建议：

实用 RESTful 设计的第一原则是：保持简单事情很简单。
保持基本 URL 简单直观。

+------------+-------------------+--------------+----------------------------------------+------------------+
| Resource   | POST create       | GET read     | PUT update                             | DELETE delete    |
| /quizzes   | Create a new quiz | List quizs   | Bulk update quizs                      | Delete all quizs |
| /quizes/12 | Error             | Show Quiz 12 | If exists update Quiz 12, if not Error | Delete Quiz 12   |
+------------+-------------------+--------------+-----------------------------------------+------------------+

关于您想要的顶级列表，也许类似于他们在“分页和部分响应”部分中概述的解决方案可能适合您的需求：

quizzes/top?limit=5

有了这个，您可以首先制作一个具有默认值（5 或 10 个项目）的资源 quizs/top，然后提供分页/更改项目数量的功能。

【讨论】：

如果您要遵循该电子书中的指南并拥有 2 个基本 URL。您将如何获得由服务器随机生成的新测验？ /quizes 是否保留用于列出所有测验（集合）？
我不是在客户端创建它，我只想从服务器生成一个
我会参加测验/随机（顺便说一句，我要编辑我的帖子以正确编写测验复数 -quizzes- :-)
但是你会违背他们的建议吗？
我想我并没有违背他们的建议（至少在广义上）：集合的第一个元素（测验），集合中特定元素的第二个元素（随机 = 随机测验只是生成）。该资源的特殊之处在于每次从服务器获取它时都会发生变化（但当有人读取“随机”时很明显）。

【解决方案2】：

这是你喜欢的。我个人喜欢 last.fm API 的工作方式：

http://www.last.fm/api/intro

但是，如果您正在寻找一些不错的标准，请查看以下帖子：

What are the best/common RESTful url verbs and actions?

How to create REST URLs without verbs?

【讨论】：

【解决方案3】：

这完全取决于您 - RESTful 模式不规定命名约定。

What are the best/common RESTful url verbs and actions?这对你有帮助吗？

只要让路线合理：例如quiz/show/{id}, quiz/top/{number} 等...

编辑：添加对路由操作命名评论的答案，取自 Rails 约定。 http://guides.rubyonrails.org/routing.html#crud-verbs-and-actions

【讨论】：

那么如何编写触发资源“进程”的路径呢？我的意思是像一个动作，而不仅仅是 CRUD 路径？
在另一个答案中，他说您应该使用 URL 来指定对象，而不是操作。嗯...所以您使用“顶部”指定对象的示例？
看这真的取决于您希望您的应用程序如何工作......您希望用户如何与您的 API 进行交互？
假设有许多不同类型的测验，例如“随机测验”，您将如何为此创建路径？获取...
所以如果你想显示一个名为“randomquiz”的测验，你会做 GET /quizes/randomquiz 如果你想创建一个“随机测验”，你会发帖到 /quizes

【解决方案4】：

按照this 文章中的说明，最好对 REST URL 使用 类似目录的结构。

类似/{type}/{operation}/{param1}/{param2}... 的网址

看起来更直观和可维护（参数太多可以作为经典?=传递）

所以在你的情况下它可以是/quiz/top/5，或者如果明天它应该是top 100，那么可以像/quiz/top/100一样重复使用

【讨论】：

【解决方案5】：

URL 标识您的对象。 HTTP 方法指定服务器应该对对象执行的操作（或操作）。

例如：

/quiz/top5

HTTP GET：客户端请求查看测验top5，这是否意味着创建一个新的？或者这是否意味着显示现有的？这取决于您（GET 的约定是在不改变服务器状态的情况下请求对象）。
HTTP POST：客户端请求持久化更改

【讨论】：

top5 部分意味着动态处理前 5 个对象的列表。所以这适合识别对象的保护伞吗？不行动？

【解决方案6】：

我建议阅读此答案https://stackoverflow.com/a/11170376/300886 来回答类似的问题。

一般来说，您应该考虑 API 的哪些部分应该可以通过 GET 访问，哪些可以通过 POST 访问。通过 GET 获得的资源通常应该用名词来描述，动作（比如可能发布一个测验的答案）应该通过 POST（或者 DELETE，也许）使用动词来描述，也许在名词之后 - 资源的名称正在采取行动。

【讨论】：