Home » Controller

Controller

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/