Pattern Sections
Pattern: Solution-Internal API
a.k.a. Application-Internal Programming Interface
Context
It has been decided to provide a subsystem of an application with a remote API that exposes one or more API endpoints, but it is not clear yet which level of visibility the API services should have. The API clients that are supposed to use the API (and therefore must reach it) are part of the same application (or solution, possibly service-based).1
Problem
How can access to and usage of an API be limited to an application, for instance, components in the same or another logical layer and/or physical tier?
Forces
The forces listed under Public API and Community API (also dealing with API visibility) apply here too:
- Business model and stakeholder concerns
- Target audience size, location, and diversity
- Complexity and maturity of required backend systems and data stores
- Security considerations
- Size, location, and technical preferences
- Lifecycle management
- Budgets
These forces are discussed in the two other patterns. For the sake of brevity, they are not elaborated upon again here.
Solution
Decompose the application logically into components. Let these components expose local or remote APIs. Offer these APIs only to system-internal communication partners such as other services in the application backend.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
In the Lakeside Mutual case study, the interface between the Customer Core and its utility services such as city lookup (by zip code) and phone number validation can be seen as examples for this pattern. The same holds for the risk calculation service:
"/riskfactor/compute": {
"post": {
"tags": ["risk-computation-service"],
"summary": "Computes the risk factor for a given customer.",
"operationId": "computeRiskFactorUsingPOST",
"consumes": ["application/json"],
"produces": ["*/*"],
"parameters":[{
"in": "body",
"name": "riskFactorRequest",
"description": "the request with customer attributes (e.g., postal code, birthday)",
"required": true,
"schema": {
"$ref": "#/definitions/RiskFactorRequestDto"
}
}],
"responses": {
"200": {
"description":"OK",
"schema": {
"$ref":"#/definitions/RiskFactorResponseDto"
}
},
"201": {
"description":"Created"
},
"401": {
"description":"Unauthorized"
},
"403": {
"description":"Forbidden"
},
"404": {
"description":"Not Found"
}
}
}
}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; many of these qualify as Solution-Internal APIs. Few of these are 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, but message-based ones are also common.
The Apigee Edge products provide product-internal management APIs for topics such as analytics and billing. Eclipse exposes many local APIs, but also enabled interprocess communication via its Eclipse Communications Framework. Built primarily for the Eclipse IDE’s collaboration and communication features, e.g. shared editing, file transfer, messaging, it can be used in any application based on Eclipse’s Rich Client Platform. The actual communication is handled by so-called distribution providers, which are implemented, amongst others, for ActiveMQ, gRPC, MQTT and Jax-RS.
Terravis (Lübke and Lessen (2016)) exposed system-internal functionalities as API operations in Solution-Internal APIs. These APIs are called by a process engine and include operations to generate documents and invoke domain-specific services. These services offer access to otherwise non-public master data such as bank partner information and payment configurations as well as non-public parcel indices (metadata).
More Information
Related Patterns
A Solution-Internal API may support Frontend Integration and/or Backend Integration. The siblings of this pattern that describe other visibility levels are Public API and Community API.
The Private Cloud pattern in Fehling et al. (2014) has a similar context and intent, but is more concerned about IT infrastructure (rather than API design).
The API refactoring Extract Endpoint splits an existing API into multiple ones.
Other Sources
The Design Practice Repository (DPR) and DPR eBook feature many techniques for API design.
Blog posts on MAP provide additional examples.
References
Note that this context is similar to that of the sibling patterns Public API and Community API.↩︎