REST API设计端点(操作/动词=>名词/资源) [英] REST API Designing Endpoints (Action/Verb => Noun/Resource )
问题描述
根据本指南 API端点，我们永远不要在URL中使用动作/动词(例如/addNewEmployee)，如果要执行动作，我们应该仅使用具有相应资源/名词的HTTP动词(例如POST /employees).
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.
那是REST.
因此，您要查找的名词是集成域中的名词，用于导航变更主题协议；换句话说，它们是表单和表单提交收件箱.
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.
您想要的思维导图不是 action (太粗体)，而是 request 的思维导图-您正在发送一条消息，询问某人 else 采取您需要的操作.实际的作用是副作用.因此，表单提交收件箱"是未决的更改主题"请求的集合.
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 几乎总是可接受的选择，用于通过以下方式发送请求不安全的语义到服务器.记住，我们在这里是因为从
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屋！
