Naming RESTful paths

Question

I am creating a web service and I have some questions regarding path names. How do you specify actions on resources in a RESTful webservice?

For example: a Quiz resource. You have normal CRUD actions and you also want to do things with the quiz. Such as generating a new quiz. That is a action. Do you use a path like /quiz/top5 or /quiz?type=top5 or what?

I don't understand how you write paths that do actions on a resource when creating a RESTful service.

I would use `/quiz/generate/123` for id `123` – Aram Kocharyan Apr 09 '13 at 15:00 — Aram Kocharyan, Apr 09 '13 at 15:00
i'ld be use `/quiz/{id}` – burning_LEGION Apr 09 '13 at 15:00 — burning_LEGION, Apr 09 '13 at 15:00

score 1 · Answer 1 · edited May 23 '17 at 11:56

1

It is what you prefer. I personally like the way the last.fm API works:

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

But if your looking for some nice standards, look at this posts:

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

How to create REST URLs without verbs?

edited May 23 '17 at 11:56

Community

1
1

answered Apr 09 '13 at 15:03

Ruben-J

2,663
15
33

jalopaba · Accepted Answer · 2013-04-09T17:38:45.073

1

I would recommend this ebook from apigee: Web API Design: Crafting Interfaces that Developers Love.

Following their advice:

The number one principle in pragmatic RESTful design is: keep simple things simple.
Keep your base URL simple and intuitive.

+------------+-------------------+--------------+----------------------------------------+------------------+
| 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   |
+------------+-------------------+--------------+-----------------------------------------+------------------+

Regarding the top list you want, maybe a solution similar to those they outline in the "Pagination and partial response" section may fit your needs:

quizzes/top?limit=5

With this, you can first craft a resource quizs/top with a default value (5 or 10 items), and later offer the ability to paginate/change the number of items.

edited Apr 09 '13 at 17:38

answered Apr 09 '13 at 15:33

jalopaba

8,039
2
44
57

If you were to follow the guidelines in that ebook and have 2 base URLs. How would you obtain a new quiz that is randomly generated by the server? Is /quizes reserved for listing all quizes ( collection )? – LuckyLuke Apr 09 '13 at 17:20
I am not creating it on the client side, I just want a generated one from the server – LuckyLuke Apr 09 '13 at 17:25
I would go for quizzes/random (BTW, I'm going to edit my post to write quiz plural -quizzes- properly :-) – jalopaba Apr 09 '13 at 17:36
But then you would break their advice? – LuckyLuke Apr 09 '13 at 17:37
I think I'm not breaking their advice (at least, in wide sense): first element for a collection (quizzes), second element for a specific element in the collection (random = random quiz just generated). The special thing for that resource is that changes every time you get it from the server (but it's clear when someone reads 'random'). – jalopaba Apr 09 '13 at 17:45

score 0 · Answer 3 · edited May 23 '17 at 11:56

0

Thats really up to you - RESTful patterns dont dictate naming conventions.

What are the best/common RESTful url verbs and actions? this may help you?

Just make the routes sensible: e.g. quiz/show/{id}, quiz/top/{number} etc...

Edit: Add answer to comment around route action naming, taken from Rails Convention. http://guides.rubyonrails.org/routing.html#crud-verbs-and-actions

edited May 23 '17 at 11:56

Community

1
1

answered Apr 09 '13 at 15:00

diagonalbatman

17,340
3
31
31

So how do you write paths that trigger a "process" on the resource? I mean like an action, not just CRUD paths? – LuckyLuke Apr 09 '13 at 15:03
In the other answer he says that you should use URLs to specify objects, not actions. Hm...so your example of using "top" specify objects? – LuckyLuke Apr 09 '13 at 15:07
Look it really depends on how you want your application to work... how do you want users to interact with your API? – diagonalbatman Apr 09 '13 at 15:17
Let say there is many different type of quiz such as "random quiz" how would you create the path for that? GET `...` – LuckyLuke Apr 09 '13 at 15:21
so if you wanted to show a quiz called "randomquiz" you would do GET /quizes/randomquiz If you want to create a "random quiz" you would do a post to /quizes – diagonalbatman Apr 09 '13 at 15:24
let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/27876/discussion-between-diagonalbatman-and-luckyluke) – diagonalbatman Apr 09 '13 at 15:28

score 0 · Answer 4 · edited May 23 '17 at 12:21

I recommend reading this answer https://stackoverflow.com/a/11170376/300886 to a similar question.

In general, you should consider what parts of your API should be available via GET, and which via POST. The resources available via GET should normally be described using nouns, the actions (like perhaps posting an answer to a quiz) should rather be available via POST (or DELETE, maybe) described using a verb, perhaps after a noun - name of the resource the action is taken on.

score 0 · Answer 5 · answered Apr 09 '13 at 15:08

Its better to use directory like structure for the REST URLs as explained in this article.

A URL like /{type}/{operation}/{param1}/{param2}...

looks more intuitive and maitainable (the param can be passed as classic ?= if they are too many)

so in your case it can be /quiz/top/5 or if tomorrow it should be top 100, then same can be reused as /quiz/top/100

Ulises · Answer 6 · 2013-04-09T15:35:47.750

0

URLs identify your objects. HTTP methods specify the action (or operation) the server should perform on the object.

For example:

/quiz/top5

HTTP GET: The client requests to see quiz top5, does this mean create a new one? or does this mean display an existing one? It's up to you (the convention for GET is to request objects without altering the state on the server).
HTTP POST: The client requests to persist changes

edited Apr 09 '13 at 15:35

answered Apr 09 '13 at 15:22

Ulises

13,229
5
34
50

The top5 part would mean to dynamically process a list of the top 5 objects. So that fits the umbrella of identifying objects? Not action? – LuckyLuke Apr 09 '13 at 15:24

Naming RESTful paths

6 Answers6