A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Also referred to as ‘custom methods’.
Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update, and delete, also known as CRUD).
One of the most common perceptions of REST’s architectural constraints is that they only apply to resources that are ‘things’ or ‘entities’ in the application domain. Although this may be true in a number of cases, scenarios that involve processing functions challenge that perception. (https://restapilinks.com/wp-content/uploads/2021/04/restful-web-services-cookbook.pdf) (p.37)
A controller resource name is a verb instead of a noun. The HTTP method on a controller SHOULD be:
- POST for actions with side effects (state change) or actions without side effects but requiring a request body
- GET for idempotent actions without side effects
Controller names typically appear as the last segment in a URI path, with no child resources to follow them in the hierarchy. The example below shows a controller resource that allows a client to resend an alert to a user:
POST /alerts/245743/resend
Before using a controller resource to represent an action, consider reifying the action as a collection or document resource (noun) describing the intent of the action. (https://www.gcloud.belgium.be/rest/#controller-vs-document)
| Controller | Controller concept |
| REST API Tutorial | https://restfulapi.net/resource-naming/ |
| Google API Cloud | https://cloud.google.com/apis/design/custom_methods (Custom methods) |
| Web services cookbook | https://restapilinks.com/wp-content/uploads/2021/04/restful-web-services-cookbook.pdf (p.39) |
| REST API Design | https://restapilinks.com/wp-content/uploads/2021/04/REST-API-Design-Rulebook.pdf (p.16) |
| Belgium government | https://www.gcloud.belgium.be/rest/#controller |
| Wahl Network | https://wahlnetwork.com/2020/01/08/resource-archetypes-and-put-and-post-methods/ |
