We also discuss related pattern languages in our API design patterns book.
Distribution and Remoting
The design of message-based remote APIs can benefit from many existing pattern works on various kinds of distributed systems, especially those related to services, as well as pattern works related to API design (e.g., API design in object-oriented programming) and enterprise integration.
In POSA vol. 4, Buschmann et al. Buschmann, Henney, and Schmidt (2007) introduce a pattern language that glues together patterns from many different pattern languages on distributed systems, ranging from architectural concerns to low-level design details of distributed systems. The Remoting Patterns language Voelter, Kircher, and Zdun (2004) specifically deals with the Broker-based design and the internal details of a middleware but also covers API-related aspects like remote objects, servants, lifecycle management at runtime, and asynchronous invocations. Asynchronous invocation plays a central role in message-oriented middleware and is covered in depth in Enterprise Integration Patterns (EIP) Hohpe and Woolf (2003). While the EIP book focuses on asynchronous messaging systems, it also covers some aspects of message-based API design. In his general treatment of enterprise application architecture, Fowler Fowler (2002) touches on many aspects of remote API design such as Remote Facades or Data Transfer Objects (DTOs). Similarly, Evans Evans (2003) covers functional API design with some of his Domain-Driven Design (DDD) patterns such as Bounded Context, Aggregate, and Service. Even basic design patterns Gamma et al. (1995) are relevant for remote API design, as they can be useful for some design aspects such as introducing a Facade or a Proxy in the API. We adopt and refine such patterns for message-based remote APIs.
Data Modeling
General data modeling patterns Hay (1996) cover data representations and meaning, but do so in the context of data storage and presentation (rather than data transport); therefore, the discussed forces and solutions to them differ from ours. Domain-specific modeling archetypes for enterprise information systems also can be found in the literature Arlow and Neustadt (2004). Neither the general nor the domain-specific data model catalogs introduced in these two books cover the specific aspects of data representation in message-based remote API communication.
Service-Orientation
Services provided by message-based remote APIs can be seen as components with remote interfaces. Such components and distributed objects are covered by the pattern languages listed above. More specifically, the work by Daigenau Daigneau (2011) provides patterns for service-based designs at the level of existing service platforms and technologies such as both REST and WSDL/SOAP-based Web services. Contract versioning for backward compatibility is one of the problem sets that is addressed in this book. In contrast, process-driven SOA patterns Hentrich and Zdun (2011) reside on a higher abstraction layer. They describe orchestrations of services based on business process or workflow engines. SOA Patterns by Arnon Rotem-Gal-Oz is largely SOA infrastructure- and platform-centric as well Rotem-Gal-Oz (2012); his patterns do not investigate message content and structure in depth.
Many other forms of interactions or message exchanges can be summarized by service interaction patterns Barros, Dumas, and Hofstede (2005). Basic and advanced conversations such as Polling are covered in the ongoing work on a Conversation Patterns language Hohpe (2007) that discusses stateful interactions composed of multiple message exchanges between loosely coupled services. In addition, Pautasso et al. Pautasso, Ivanchikj, and Schreier (2016) describe conversations specific to RESTful services. The application of the interface representation patterns from this paper is closely related to the application of conversation patterns and vice versa: Each message exchange in a conversation requires request and response messages which need interface representations. Coarse-grained APIs often are used in simple conversations, whereas fine-grained ones lead to more chatty conversations.
Emerging distributed system architectures like cloud computing and the microservices approach to service-based systems Lewis and Fowler (2014) require many distributed system patterns to build remote APIs, but also bring their own patterns or flavors of related patterns with them Richardson (2018). The Data Abstractor pattern in Fehling et al. (2014) is an example.
Also complementary to our patterns, Kyle Brown and his co-authors share work-in-progress “Cloud Adoption Patterns”. The evolution of this pattern language and the tooling are explained in a blog post on Medium.
Other Sources
Complementary to pattern languages, platform-specific best practices and design guides have also been published, e.g., recipes in a RESTful HTTP Cookbook Allamaraju (2010) and decisions required in Web services design and related best practices Zimmermann, Tomlinson, and Peuser (2003).