REST API Designing Endpoints (Action/Verb => Noun/

Question

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).

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

GET /themes (list all themes)

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

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.

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.

Answer 1

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

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 gave a really good talk on this.

Please guide me how should I proceed in such scenario.

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.

That's 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 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 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.

Answer 2

PUT /themes/:name

This mean you will change this single Theme. You can pass some of the properties and only change them.