February 2021 Summaries

API design often requires moving beyond the traditional CRUD model to accommodate actions like submit, approve, and decline, which are essential for capturing state transitions in business workflows. By using specific HTTP methods and adopting a clear URL convention, API designers can effectively extend resource lifecycles, providing fine-grained access control and improved auditability by assigning unique URLs to different actions. For instance, in a content management system, operations such as POST /articles/{articleId}/submit or /approve allow for explicit workflows without relying solely on modifying a status field through PATCH requests. This approach not only enhances flexibility and security but also enables consumers to easily understand available actions based on their permissions, thus making the workflow more transparent and manageable.

The article explores strategies for designing REST-based APIs to handle long-running background jobs efficiently, addressing challenges such as resource consumption and potential connection issues. It emphasizes the use of the HTTP 202 Accepted response code to inform clients that a request is being processed asynchronously, directing them to a specific URL for status updates. The piece also discusses alternatives to constant polling, like Webhooks, server-sent events, and WebSockets, which can notify clients when a job is complete. By implementing these techniques, developers can prevent resource overload and ensure smoother API operations, particularly when dealing with unpredictable processing times caused by legacy systems or third-party integrations.

Singleton resources in API design represent a single instance of a resource, as opposed to a collection, and are particularly useful when a collection is unnecessary. This design pattern can simplify APIs by providing a direct interaction point, such as a user's unique profile or preferences, and avoids confusion associated with trying to apply CRUD operations to non-collection resources. Singleton resources allow for straightforward API shortcuts, like GET /me for user identification, and offer flexibility by using HTTP methods like PUT and POST to manage their lifecycle, often adhering to an upsert pattern. However, it is crucial to assess whether a resource might require full CRUD support in the future, as transitioning from a singleton to a CRUD-based resource can result in breaking changes.