Link

Patterns

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 Profile and Link headers.

Patterns can offer extensions that expand the capabilities of the pattern. For example, the List pattern has a Editable List pattern extension that provides edit controls for the List. The extension patterns mix into the main pattern by adding additional Profile and Link headers.

Similarly, a resource may participate in more than one pattern. A Tree pattern implementation may also utilize the Filter pattern so clients can filter nodes from their result. Similarly, a Sort pattern can be added to this combination to add tree node sorting. This approach is different than Profile mixins in that the Sort and Filter pattern can stand alone. They can present their abilities to a resource with a list-like data structure.

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.

Patterns as Profiles

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 Link and 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.

Patterns can be Combined

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.

Pattern Listing


Copyright © 2019 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.