命名 RESTful 路径

Posted 2023-03-31

技术标签:

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

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

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

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

【问题讨论】：

我会使用 /quiz/generate/123 作为 id 123 我会使用/quiz/id 【参考方案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 方法指定服务器应该对对象执行的操作（或操作）。

例如：