Quality Patterns

An API provider has to compromise between providing a high-quality service in a cost-effective way. The patterns in this category are all addressing or contributing to the following overarching design issue:

How to achieve a certain level of quality of the offered API, while at the same time utilising the available resources in a cost-effective way?

Structure Patterns Evolution Patterns

Category Overview

The Quality Patterns category comprises the following patterns:

Quality

Reference Management

Embedded Entity
Linked Information Holder

Data Transfer Parsimony

Pagination
Wish List
Wish Template
Conditional Request
Request Bundle

Quality Management and Governance

Pricing Plan
Rate Limit
Service Level Agreement

Quality of an API has many dimensions, starting with the functionality described in the API contract, but also including many other qualities such as reliability, performance, security, scalability. Some of those technical qualities are often referred to as Quality of Service (QoS) properties. They might be conflicting and almost always need to be balanced with economic forces such as costs, time to market. There are many quality measures related to QoS of services or distributed systems in general, but only few of them directly concern the APIs.

Most decisions in this category have to be made for combinations of API clients and the APIs those clients can access. Many decisions can be made for large groups of those combinations, such as all clients with freemium access to an API or all clients accessing a specific API. One decision (Avoid Unnecessary Data Transfer) needs to be made at the level of operations in the API.

The following patterns of the quality category have been published so far:

Data Transfer Parsimony

Pattern: Pagination
Problem How can an API provider deliver large sequences of structured data without overwhelming clients?
Solution Divide large response data sets into manageable and easy-to-transmit chunks (also known as pages). Send one chunk of partial results per response message, and inform the client about the total and/or remaining number of chunks. Provide optional filtering capabilities to allow clients to request a particular selection of results. For extra convenience, include a reference to the next chunk/page from the current one.
Pattern: Wish List
Problem How can an API client inform the API provider at runtime about the data it is interested in?
Solution As an API client, provide a Wish List in the request that enumerates all desired data elements of the requested resource. As an API provider, deliver only those data elements in the response message that are enumerated in the Wish List ("response shaping").
Pattern: Wish Template
Problem How can an API client inform the API provider about nested data that it is interested in? How can such preferences be expressed flexibly and dynamically?
Solution Add one or more additional parameters to the request message that mirror the hierarchical structure of the parameters in the corresponding response message. Make these parameters optional or use Boolean as their types so that their values indicate whether or not a parameter should be included.
Pattern: Conditional Request
Problem How can unnecessary server-side processing and bandwidth usage be avoided when frequently invoking API operations that return rarely changing data?
Solution Make requests conditional by adding Metadata Elements to their message representations (or protocol headers) and processing these requests only if the condition specified by the metadata is met.
Pattern: Request Bundle
Problem How can the number of requests and responses be reduced to increase communication efficiency?
Solution Define a Request Bundle as a data container that assembles multiple independent requests in a single request message. Add metadata such as identifiers of individual requests and bundle element counter.

Reference Management

Pattern: Embedded Entity
Problem How can one avoid sending multiple messages when their receivers require insights about multiple related information elements?
Solution For any data relationship that the client wants to follow, embed a Data Element in the request or response message that contains the data of the target end of the relationship. Place this Embedded Entity inside the representation of the source of the relationship.
Pattern: Linked Information Holder
Problem How can messages be kept small even when an API deals with multiple information elements that reference each other?
Solution Add a Link Element to messages that pertain to multiple related information elements. Let this Link Element reference another API endpoint that represents the linked element.

Quality Management and Governance

Pattern: Pricing Plan
Problem How can the API provider meter API service consumption and charge for it?
Solution Assign a Pricing Plan for the API usage to the API Description that is used to bill API customers, advertisers, or other stakeholders accordingly. Define and monitor metrics for measuring API usage, such as API usage statistics per operation.
Pattern: Rate Limit
Problem How can the API provider prevent API clients from excessive API usage?
Solution Introduce and enforce a Rate Limit to safeguard against API clients that overuse the API.
Pattern: Service Level Agreement
Problem How can an API client learn about the specific quality-of-service characteristics of an API and its endpoint operations? How can these characteristics, and the consequences of not meeting them, be defined and communicated in a measurable way?
Solution As an API product owner, establish a structured, quality-oriented Service Level Agreement that defines testable service-level objectives.

Earlier versions of five of these patterns are featured in our EuroPLoP 2018 paper Interface Quality Patterns: Communicating and Improving the Quality of Microservices APIs. A free PDF version of this paper can be downloaded here.

Pattern Index

Foundation Patterns

Responsibility Patterns

Structure Patterns

Quality Patterns

Evolution Patterns

Cheat Sheet