The book features a more extensive cheat sheet for pattern selection in its Appendix A, which also discusses how our patterns relate to ADDR, RDD and DDD.
The cheat sheet is ordered chronologically. Its issue-pattern tables suggest when to apply which pattern. 1
Warning: The cheat sheet is a gross simplification of a set of complex design considerations; API design is a wicked problem. The pattern texts discuss forces and consequences of solutions in depth.
Getting Started with API Design
The patterns in the Foundations category address the following early and basic API scoping issues:
| Issue | Patterns to Consider | Criteria |
|---|---|---|
| I want to expose an API | Frontend Integration or Backend Integration | Type of client, business model, product/project vision |
| The new API should be broadly accessible | Public API | Business model, location and number of clients, security requirements |
| The visibility of the new API should be restricted | Community API or Solution-Internal API | Business model, location and number of clients, security requirements |
Note that we do not go into decisions about integration styles and architectures in MAP; other pattern languages do so. For example, try the Enterprise Integration Patterns and the Cloud Computing Patterns websites supporting the respective patterns books.
Domain-Driven Design (DDD) (Evans (2003), Vernon (2013)) and our responsibility category can jump start API endpoint and operation design:
| Issue | Patterns |
|---|---|
| Identify API endpoint candidates | Define one endpoint for each Bounded Context from DDD if logic and data are highly cohesive |
| Alternatively, define one endpoint for each Aggregate from DDD if fine-grained decomposition is desired and possible | |
| Model a business capability that is activity-oriented | Introduce a Processing Resource and implement the required coordination and state management in its operations (see below) |
| Model a business capability that is data-oriented | Introduce an Information Holder Resource, being aware of the coupling introduced and add suited operations to it (see below) |
| Expose long-lived data (mutable, immutable) | Mark Information Holder Resource as Master Data Holder or Reference Data Holder |
| Expose short-lived, transaction(al) data | Mark Information Holder Resource as Operational Data Holder |
| Let clients exchange transient data | Introduce a Data Transfer Resource |
| Introduce an endpoint directory | Provide a Link Lookup Resource |
| Allow API client to initialize provider-side state | Mark operation as write-only State Creation Operation |
| Allow API client to update provider-side state | Mark operation as read-write State Transition Operation |
| Allow API client to read provider-side state | Mark operation as read-only Retrieval Operation |
| Allow API client to invoke a stateless operation | Mark operation as Computation Function |
The structure category deals with message payload design, i.e., with the representation elements taking certain stereotypical roles:
| Issue | Patterns |
|---|---|
| Specify data contract (payload structure) | Use Atomic Parameter and/or Atomic Parameter List if data is simple |
| Use Parameter Tree and/or Parameter Forest if data is complex | |
| Exchange structured data (payloads) | Add Data Element with one or more Embedded Entities (following relationships) to payload |
| Distinguish representation elements | Add Id Element to payload |
| Inflexible, static operation (work-)flow | Upgrade from Id Element to Link Element to support HATEOAS |
We only touch upon protocol specifics in our examples and
implementations hints; the recipes in Allamaraju (2010) provide detailed advice regarding
RESTful HTTP. Technology blogs and other sources of information are
compiled in the side bar “staying current” in this
magazine article.
API Release and Productization
Once an API goes into production, quality management and governance tasks come into play. Several of the patterns in the quality category address such concerns:
| Issue | Patterns |
|---|---|
| Clients need to know how to call the API | Create and publish an API Description |
| Document terms and conditions | Use Service Level Agreement or informal specification |
| Make API robust and elaborate/expressive | Add an Error Report to response representations |
| Ensure fair use of the API | Enforce a Rate Limit |
| Make profit with API | Establish a Pricing Plan |
Continuous API Improvement
Other patterns, for instance from the quality category, can help to size message representations right (the goal is to achieve data transfer parsimony):
| Issue | Patterns |
|---|---|
| API clients report interoperability and usability problems | Switch from minimal to full API Description |
| Introduce a Context Representation in the payload encapsulating control metadata such as QoS properties | |
| My clients report performance problems | Switch from Embedded Entities to Linked Information Holders |
| Reduce transferred data with a Wish List or a Wish Template | |
| Consider any other Quality Pattern improving data transfer parsimony (e.g., Conditional Request, Request Bundle) | |
| Introduce Pagination | |
| Access control is needed | Introduce API Keys or full-fledged security (CIA/IAM) solution such as OAuth |
API Support and Maintenance
Finally, API providers have to deal with change and must balance compatibility and extensibility. The evolution category covers strategies for doing so:
| Issue | Patterns |
|---|---|
| Make changes that are not backward compatible | Introduce a new API operation or provide a Version Identifier |
| Communicate impact and significance of changes between versions | Apply Semantic Versioning |
| Maintain several versions of API endpoints and their operations | Offer Two in Production |
| Avoid supporting multiple versions | Plan Aggressive Obsolescence |
| Commit to keeping my API available and supported for certain, distinct amount of time | Declare Limited Lifetime Guarantee |
| Commit to keeping my API available and supported for unlimited amount of time | Promise Eternal Lifetime Guarantee |
| Avoid committing stability and existence of API and its operations | Declare API as Experimental Preview |