Microservice API Patterns (MAP)

Remote Application Programming Interfaces (APIs) are technology enablers for distributed systems and cloud-native application development. API providers find it hard to design their remote APIs so that they can be evolved easily; refactoring and extending an API while preserving backward compatibility is particularly challenging. If APIs are evolved poorly, clients are critically impacted; high costs to adapt and compensate for downtimes may result. For instance, if an API provider publishes a new incompatible API version, existing clients might break and not function properly until they are upgraded to support the new version. Hence, applying adequate strategies for evolving service APIs is one of the core problems in API governance, which in turn is a prerequisite for successfully integrating service providers with their clients in the long run. Although many patterns and pattern languages are concerned with API, service design, and related integration technologies, patterns guiding the evolution of APIs are missing to date. Extending our emerging pattern language on Microservice API Patterns (MAP), we introduce a set of patterns focusing on API evolution strategies in this paper: API Description, Version Identifier, Semantic Versioning, Eternal Lifetime Guarantee, Limited Lifetime Guarantee, Two in Production, Aggressive Obsolescence, and Experimental Preview. The patterns were mined from public Web APIs and industry projects the authors had been involved in.

The design and evolution of Application Programming Interfaces (APIs) in microservices architectures is challenging. General design issues in integration and programming have been covered in great detail in many pattern languages since the beginnings of the patterns movement, and service-oriented infrastructure design patterns have also been published in the last decade. However, the interface representations (i.e., the content of message payloads) have received less attention. We presented five structural representation patterns in our previous work; in this paper we continue our coverage of the API design space and propose five interface quality patterns that deal with the observable aspects of quality-attribute-driven interface design for efficiency, security, and manageability: An API Key allows API providers to identify clients. Providers may offer rich data contracts in their responses, which not all consumers might need. A Wish List allows the client to request only the attributes in a response data set that it is interested in. If a client makes many API calls, the provider can employ a Rate Limit and bill clients according to a specified Rate Plan. A provider has to provide a high-quality service while at the same time having to use its available resources economically. The resulting compromise is expressed in a provider's Service Level Agreement.

The Microservice API Patterns (MAP) language and supporting website premiered under this name at Microservices 2019. MAP distills proven, platform-and technology-independent solutions to recurring (micro-)service design and interface specification problems such as finding well-fitting service granularities, rightsizing message representations, and managing the evolution of APIs and their implementations. In this paper, we motivate the need for such a pattern language, outline the language organization and present two exemplary patterns describing alternative options for representing nested data. We also identify future research and development directions.

Microservice API Patterns (MAP) take a broad view on API design and evolution, primarily focussing on message representations – the payloads exchanged when APIs are called. These payloads have structure. The representation elements in the payloads differ in their meanings as API endpoints and their operations have different architectural responsibilities. Furthermore, the chosen representation structures strongly influence the design time and runtime qualities of an API. Finally, the evolution of API specifications and their implementations has to be governed. Our Microservice API Patterns capture proven solutions to design problems commonly encountered when specifying, implementing and maintaining message-based APIs in terms of their structure, responsibilities, and quality.