Pattern Sections
Pattern: Community API
Context
It has been decided to provide a (sub-)system with a remote API that exposes one or more API endpoints, but it is not clear yet how visible this API should be. The API clients that are supposed to use the API (and therefore must reach it) reside in different parts of the organization owning and operating the (sub-)system.1
Problem
How can the visibility of and the access to an API be restricted to a closed user group that does not work for a single organizational unit but for multiple legal entities (such as companies, nonprofit/nongovernment organizations, and governments)?
The visibility of an API is determined by the deployment location and its network connections (e.g., the Internet, an extranet, or a company-internal network or even a single data center).
Forces
The forces listed for the two sibling patterns Public API apply to Community APIs as well; for the sake of brevity, these forces are not repeated here. Community APIs might be harder to conceptualize, implement and deploy because of:
- Size, location, and technical preferences of the community
- Stakeholder concerns
- Lifecycle management
- Budgets (development and operations, maintenance and evolution)
- Community-specific security considerations
Pattern forces are explained in depth in the book.
Solution
Deploy the API and its implementation resources securely in an access-restricted location so that only the desired user group has access to it—for instance, in an extranet. Share the API Description only with the restricted target audience.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
In the current implementation of Lakeside Mutual, our fictitious insurance case study, the interfaces between bounded contexts in the backend qualify as examples, for instance, the API exposed by the customer core service and consumed by policy management, customer management and customer self service. See here for an overview of all patterns demonstrated in the Lakeside Mutual services.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
Many internal APIs exist in firms, government agencies, and other organizations around the world; some of these qualify as Community APIs. One example is the SWITCH edu-ID, an identity management solution for Swiss universities and affiliated institutions. More often, such APIs are not documented publicly; for some of them, experience reports have been published. Object-oriented APIs and classical RPCs can be found more often in solution- and company internal integration efforts (that are inherently synchronous), but message-based ones are also common due to their non-blocking behavior that makes it easier to support resiliency.
An report on the SOA and Enterprise API evolution at Credit Suisse can be found in Murer and Hagen (2014). The Dynamic Interface, described in Brandner et al. (2004) is a Product API.
Terravis as portrayed by Lübke and Lessen (2016) provides Community APIs as well. Here, the community is legally constrained as only certain organizations may access land registry data. Only organizations in this community are able to use the APIs at all. Another known use is the wholesale-retail order management SOA described in Zimmermann et al. (2005). All of these expose frontend-to-backend as well as backend-to-backend APIs to closed user groups, sometimes using an Extranet rather than the public Internet.
More Information
Related Patterns
A Community API either supports Frontend Integration or Backend Integration scenarios. The siblings of this pattern that describe other visibility levels are Public API and Solution-Internal API.
The Community Cloud pattern documented in Fehling et al. (2014) has a similar context and intent, but is more focused on IT infrastructure rather than API design.
Other Sources
“Managed Evolution” (by Murer, Bonati, and Furrer (2010)) provide advice how to organize a company-wide API management program. Note that different terminology is used in the book due to its SOA focus.
References
Note that this context is similar to that of the sibling patterns Public API and Solution-Internal API.↩︎