A Level 3 pattern combines two or more resources into a more-useful whole. These patterns solve common interaction problems API designers face and give the client consistent experiences across different API domains. The pattern descriptions have a joint presentation format, which includes
Patterns can offer extensions that expand the capabilities of the pattern. For example, the List pattern has a Pageable List pattern extension that provides pagination controls for the List. The extension patterns mix into the main pattern by adding additional
Pattern resources occasionally include properties that the client can expect to find and utilize. These properties are minimal, not exhaustive, meaning implementations of a pattern might include more properties, but they must include the properties defined in the pattern.
A resource that is participating in a pattern includes their part in that pattern in their
Profile headers list. For instance, if a Nexus resource is part of a List pattern implementation, the header is:
Profile: <http://level3.rest/profiles/nexus>, <http://level3.rest/patterns/list#list-resource>
These headers give the client the necessary information they need to interact with the resource in its pattern’s context. As a key, these profile types have an icon to help identify their roles in the diagrams. Note that mixin profiles are not included in patterns, but are naturally part of the resource’s individual client experience. Patterns do not require mixin profiles to function.
In some cases, multiple profiles are acceptable for a given resource, and in that case, the diagrams include both, separated by a pipe character:
In other cases, the pattern has no specification for the profile of the resource, so it indicates this with the question mark:
Each pattern has a diagram showing the link relations between the resources. These link relations use simple string names for clarity. In practice, they should be fully-realized URLs, as per the Web Linking standard for extension relations.
Every pattern definition includes a description of each relationship name detailing its full name and meaning. Patterns may not require every relation; those that are optional use dotted arrows and italicized relation names.
IANA’s link relation registry may be useful in some API designs, but Level 3’s pattern catalogue has chosen to always use extension relations instead of the registry. The primary reason is to inform the client of the pattern’s context for the relation. A client can follow the relationship URL to this documentation to learn what the relationship means in the pattern.
The pattern descriptions are link targets in
Profile headers so that clients can inspect a running API, follow the links to this site and learn the specifics of the profile or link relations. These URIs utilize fragments to point to a relevant part of the pattern on the page.
Level 3 resource patterns can overlap and are simultaneously utilizable. When the patterns are combined, changes in one pattern configuration does not reset the other pattern’s configurations. For instance, the List pattern can combine the Filter, Page and Sort patterns to create a full-featured list API. If a client is sorting the list by a “first-name” property, and then changes the page number in the Pagination control, the “first-name” sort ordering still applies to the list.
Copyright © 2019 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.