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.

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