Published: 20 May 2023
The notion of Processing Resource as an endpoint role offering an activity-oriented API endpoint automatically brings us to the discussion how to define transactions as (REST) resources in the URI endpoint of the HTTP API. Should the URL be verb-free? This is still a hot debate in the REST API design community (so is the discussion between REST vs RPC). Some will argue that using verbs in data-oriented API endpoints will enrich the semantics of the API, others see it as an anti-pattern. Further inspiration on this subject: https://tyk.io/blog/rest-never-crud/ by James Higginbotham. This valuable link is of course provided in the book (amongst many others)!
Known Uses
n/a
Discussion Input and Recommended Reading
The notion of activity-oriented API roles and processing resources endpoints is in the original literature very often associated with the controller resource archetype. Examples:
- RESTful Web Service Cookbook (Allamaraju 2010): In order to abstract complex business operations (including transactions), servers may need to employ controller resources to make changes to other resources (e.g. Recipe 2.6);
- REST API Design Rulebook (Massé 2012): A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs;
- https://restfulapi.net/resource-naming/: Use verb to denote controller archetype;
Informative link and resource that talk about RPC and REST (understanding the difference might help in understanding the Processing Resource pattern:
- https://nordicapis.com/whats-the-difference-between-rpc-and-rest/
- Principles of Web API Design (Higginbotham 2021): Chapter 8 – and see an example of transaction approach in ’Long-Running Transaction Support in REST (pages 135 to 136);
With regard to the API endpoints must be verb-free debate it’s worthwhile to mention:
- Zalando: https://opensource.zalando.com/restful-api-guidelines/#141: keep URLS verb-free;
- Dutch government: https://publicatie.centrumvoorstandaarden.nl/api/adr/#operations: the imperative mood of a verb can be used, prefixed with an underscore
_to distinguish these resources from regular resources; - Web API Design: The Missing Link (Apigee 2018): In URLs, nouns are good; verbs are bad;
- https://www.belgif.be/specification/rest/api-guide/#controller: controller usage in API guidelines Belgium government;
- https://youtu.be/k5S3qcCFDiQ?t=3008: Crafting business-oriented web APIs by Julien Topçu: Using verbs enrich the semantics of the API;
This is of course a simple fragment of what is being offered by the web community, hopefully it adds some inspiration and ideas!
Read the complete pattern on api-patterns.org