REST API 设计端点(操作/动词 => 名词/资源) [英] REST API Designing Endpoints (Action/Verb => Noun/Resource )

问题描述

根据本指南设计RESTAPI 端点，我们不应该在 URL 中使用动作/动词(例如 /addNewEmployee)，如果我们想执行一个动作，我们应该只使用带有相应资源/名词的 HTTP 动词(例如 POST/员工).

According to this guide of designing REST API endpoints, we should never use action/verbs in URL (e.g. /addNewEmployee), if we want to perform an action we should only use HTTP verbs with respective resource/noun (e.g. POST /employees).

现在，我有一个名为 themes 的资源，我围绕它创建了以下端点:

Now, I've a resource named themes, I've created following endpoints around it:

GET/themes(列出所有主题)

GET/themes/:name(列出给定名称的单个主题)

GET /themes/:name (list a single theme with given name)

我想创建另一个端点，通过它我可以执行操作(即切换主题)，此操作将更改数据库中 Settings 表中的 current_theme 字段值.我不确定这样做的最佳实践是 REST API 时尚并且对消费者来说也是直观的.

I wanted to create another endpoint through which I can perform an action (i.e. switch theme), this action will change current_theme field value in Settings table in DB. I'm not sure what would be the best practice to do this is REST API fashion and also be intuitive for the consumer.

我可以这样做 POST/themes/changeTheme 或 PUT/themes/:name/activate 但再次 changeTheme 和 activate 是动词.我也可以这样做 PUT/settings 但从 API 使用者的角度来看它似乎并不直观.请指导我在这种情况下我应该如何进行.

I can do this POST /themes/changeTheme or PUT /themes/:name/activate but again changeTheme and activate are verbs. I can also do this PUT /settings but it does not seem intuitive from API consumer's point of view. Please guide me how should I proceed in such scenario.

推荐答案

根据这个设计 REST API 端点的指南，我们永远不应该在 URL 中使用动作/动词

According to this guide of designing REST API endpoints, we should never use action/verbs in URL

REST 不关心您为标识符使用什么拼写.这是重点的一部分./e25928c5-7b4e-44b8-be83-24ed9c9f8d3b 是一个完美的标识符.

REST doesn't care what spellings you use for your identifiers. That's part of the point. /e25928c5-7b4e-44b8-be83-24ed9c9f8d3b is a perfect fine identifier.

Stefan Tilkov 就此发表了精彩的演讲.

Stefan Tilkov gave a really good talk on this.

请指导我在这种情况下应该如何进行.

Please guide me how should I proceed in such scenario.

想一想您将如何使用网站来做到这一点.你会在某个页面上，有一堆链接，其中一个上面有一个标签，比如changeTheme.您将单击该链接，并会看到一个包含表单的新页面，其中包含可用主题列表.您将从列表中选择所需的主题，然后提交表单.该请求将发送到后端，更新一些资源.作为副作用，您的主题记录将被更改.您可能会收到一条消息，告诉您已进行更改，将您重定向回开始的位置.

Think about how you would do it with a website. You would be on a page somewhere, with a bunch of links, one of which had a label on it like changeTheme. You would click that link, and be presented with a new page that included a form, with a list of available themes. You would pick the theme you want from the list, and submit the form. That request would go off to the back end, updating some resource. As a side effect, the record of your theme would be changed. You would get back perhaps a message telling you that the change had been made, redirecting you back to where you started.

这就是休息.

因此，您要查找的名词是集成域中用于导航更改主题协议的名词；换句话说，它们是表单和表单提交收件箱.

So the nouns you are looking for are the nouns in the integration domain that you are using to navigate the change theme protocol; in other words, they are the form, and the form submission inbox.

Jim Webber 将网络模型描述为 1950 年代的办公室；您可以通过检索表单、填写表单并将其放入收件箱来完成工作.

Jim Webber describes the model of the web as that of a 1950's office; you get work done by retrieving forms, filling them out, and dropping them into inboxes.

你想要的心理映射不是一个动作(这太大胆了)而是一个请求——你正在发送一条消息询问别人 采取您需要的操作.实际作用是副作用.所以表单提交收件箱"是待定更改主题"的集合请求.

The mental mapping you want is not that of an action (that's too bold) but of a request -- you are sending a message asking somebody else to take the action you need. The actual action is the side effect. So the "form submission inbox" is the collection of pending "change theme" requests.

使用任何本地拼写约定来处理这类事情.

Use whatever the local spelling convention is for that sort of thing.

不要认为资源代表您的领域；资源支持您的集成协议，并且资源的名称来自您的集成域的语言，而不是您的业务域的语言.

Stay away from the idea that the resources are representations of your domain; the resources support your integration protocols, and the names of the resources are drawn from the language of your integration domain, not the language of your business domain.

POST 几乎总是可以接受的发送选择向服务器发送带有不安全语义的请求.请记住，我们来到这里是因为网络有效，从 一种媒体类型，仅支持 GET 和 POST.

POST is almost always an acceptable choice for sending requests with unsafe semantics to the server. Remember, we're here because the web worked, starting from a media type that supported only GET and POST.

这篇关于REST API 设计端点(操作/动词 => 名词/资源)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！