RESTalk Pattern Language

Patterns for RESTful Conversations

Resources exposed as part of RESTful APIs are discovered by clients that interact with them over conversations, composed of sets of basic HTTP interactions, to achieve different goals, such as for example: the (reliable) creation of additional resources, the discovery of related resources, the enumeration of the items found within a collection. Given the goal of each conversation, the designer of the API chooses the corresponding conversation patterns which form the basis for the API design. These patterns will thus help the client developer to understand API’s features and to build upon them clients that will perform the complex conversation to achieve their goals.

What are patterns?

Each pattern describes a problem which occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice.

Christopher Alexander et al. in A Pattern Language: Towns, Buildings, Construction (1977)

You can find an explanation what patterns are and how they are described on the website of the EuroPlop conference.

RESTalk Patterns

An overview over the patterns of this language and their relationships is provided in the following figure.

image/svg+xml POST OnceExactly POST-PUTCreation (Partial) ResourceEditing Conditional Update for Large Resources Long RunningOperation withPolling Server-side Redirection with Status Codes Client-side Navigation following Hyperlinks Incremental Collection Traversal Basic Resource Authentication Cookie-basedAuthentication POST newCollection Item Resource Protection Resource Life Cycle Discovery & Navigation Reliable Creation Resource Editing Resource Creation if creation takes time avoid duplicates if all or some resources of theconversation need to be protected for browsers or adaptable login for non-browser clients can be used in parallel extend with in case of large representations avoid duplicates editing combine with to discover edit option if creationtakes time if results can befurther processed based on for redirection to login in case of multiple options when jobs or results are reorganized based on discover created elements if only onealternativeor moving/reorganizing based on in case of large representations
Pattern Language Overview

The patterns are grouped by the problem they are solving into the following groups. The missing patterns will be published soon.

Resource Creation Patterns

While HTTP offers the POST and PUT methods for creating resources in a single request-response round, these patterns deal with resource creation under certain constraints or failure scenarios.

Resource Discovery Patterns

The HATEOAS (Hypermedia as the engine of application state) constraint, promotes the design of APIs featuring a single entry point URI, and the dynamic resource discovery based on hypermedia. However, the entry point URI might not lead directly to the resource needed by the client, due to access rights, or the resource being moved to a different location, or the resource being part of a collection of resources. Therefore, these patterns help to discover resources in such situations.

Resource Editing Patterns

The read-only Web is long gone and editing resources has become a common operation which can be performed using these patterns.

Depending on the resource’s content, some or all of the CRUD (Create, Read, Update, Delete) operations might be available only to a restricted group of clients. Client’s access rights can be controlled using these patterns.

Resource Protection Patterns

License

We plan to publish this content under a non-commercial Creative Commons license. But until the clarification of some legal issues, the copyright stays with the authors.