API Interoperability Maturity Model
A Model for the Evolution of REST Enabled Interoperability
As domain autonomy increases, so do the integration and dependency management challenges. Left unmitigated, these challenges will become a drag on agility. So how do we facilitate and measure progress toward API maturity in ways that make a material difference to interoperability?
API Maturity Models
The Richardson Maturity Model and Web API Design (Amundsen) Maturity Model are highly regarded models of API maturity. However, in an enterprise environment in which an API Management capability is a given, reliance on these maturity models alone, as worthy as they are, can lead to inconsistent guidance, impede discoverability, and leave important challenges unaddressed.
APIs do not exist in a vacuum. Implementation must be decoupled, but also consistent both across the enterprise and within a multi-modal interoperability framework.
When taking an organizational view of REST enabled interoperability there are many highly impactful considerations that might be embraced by a maturity model — such as the consistency of APIs, provenance and quality of the model, security, interoperability with asynchronous events, contribution to a federated data platform and frictionless API management.
An exploration of the Richardson and Amundsen maturity models and tactics to improve compatibility with specification-first imperatives and URL versioning are covered in the related article The Engine of Application State | by TRGoodwill | Aug, 2022 | MediumA Managed API Interoperability Maturity Model
This article introduces an API interoperability maturity model specifically tailored to a multi-domain managed API capability context. The intention is not to be prescriptive, rather to identify challenges and opportunities, spark discussion and hopefully inspire the adoption of an agreed and contextually fit-for-purpose model of API interoperability maturity to inform intermediate and target-state architectures and frameworks.
The focus of this maturity model is the API design qualities as expressed in by the API specification document. Maturity is a measure of the domain alignment and interoperability qualities of resource APIs, and thus is also concerned with strategic guidance.
The trend in diagramming such things appears to be four levels starting from zero, and arrows indicating progress from bottom to top. Let’s go with that.
Level 0 — No Domain Model and/or No API Development Standards
Level zero represents the lowest barrier to entry to REST-like APIs for a large enterprise, and might take one of two forms; reactive and project driven, or centralized control. Each is deeply problematic.
Reactive and Project Driven
The need to exchange data via REST APIs ahead of any coherent enterprise strategy will typically result in project focused, highly coupled APIs with little potential for reuse. APIs may have been delivered across the organization with little consistency or predictability, and hosted without an API management/portal service, or across multiple API management platforms. There is likely no self-service integration and perhaps inconsistent, incompatible security architectures.
Centralized Control
A competency center may grow out of a centralized SOA/ESB integration capability, or a pilot REST API capability. Typically the competency center will be responsible for REST models, API lifecycles and dependency management, and responsibilities may extend to supporting platforms.
Although the approach may deliver some of the benefits of level 1 maturity, such as consistent models and interfaces, it does so at the cost of a blocking dependency on a central team. Agility is limited. CI/CD aligned with product streams is unlikely to be supported.
Level 1 — Minimum Viable Domain Model and API Development Standards
Domain Autonomy
At baseline (Level 1) maturity, domains are identified, and provided with reserved domain namespaces. SMEs still review REST models, however model development, implementation and deployment are under the control of responsible domains. Domain decoupling is facilitated by an API Management platform which segregates API lifecycle and workflow roles and responsibilities by domain, while supporting a single portal and a single enterprise catalog for API discovery. API version management and depreciation schedules are employed to provide stability and reduce coupling.
Data Stewardship and Oversight
The “enterprise data model” exists only as a federated model, an aggregate of the contributions of relevant subject/domain matter experts, each working within their allocated functional space. Guidance and active engagement by the responsible enterprise office will ensure consistency between domain models, semantic interoperability, appropriate security classification and transparent management of dependencies.
Enterprise API Standards
API Design Standards are a focused collection of imperatives, conventions and guidance, and are intended to improve the consistency, stability, generality, predictability and usability of business resource APIs. They may articulate enterprise, industry and regulatory policies and frameworks. They may offer best-practice recommendations and provide a basis for quality assessment.
Experience APIs
UI/Experience APIs will tend to be tailored to specific applications (SPA/PWA/Mobile) or use-case requirements. Enterprise data requirements are mediated to and from enterprise resource-oriented and functional APIs. In this model, level 1 would be the target maturity level for these APIs. Closer alignment to a domain model or registration as a discoverable domain API may not applicable, or desirable.
Level 2 — Strong Domain Model, Strong Interoperability Strategy and Standards
Robust interoperability demands a consistent approach to synchronous APIs and asynchronous events, so that each business capability contributes to a dynamic enterprise catalog of discoverable, predictable, composable, coherent and subscribable business resources.
Domain Driven Design
Domain Driven Design (DDD) “divides up a large system into Bounded Contexts, each of which can have a unified model” Fowler, M 2014, BoundedContext. DDD tooling and practices (such as Event Storming) are defined and may be guided, however individual business domain owners own the process, as well as the domain models, capabilities and interfaces that are derived from it. The process must be open and multidisciplinary, iterative, and learn from the realities of implementation.
The Domain Model and Model Driven Design
Through a process of broad stakeholder consultation, distillation and frequent iteration, stakeholders will build a comprehensive model of the domain by identifying aggregate roots and boundaries, entities and value objects, vocabulary, business events and state-lifecycle, commands and assertions, context and dependencies. It will explore existing applicable formalisms such as industry models and frameworks.
The model is rigorously maintained as the source-of-truth document for the capabilities and interfaces that implement it.
The Domain Model and Model Driven Design are further discussed hereThe Canonical Business Resource
A canonical business resource represents the scope and context of the business information managed by a system of record — the business facts about a domain with which external systems can interact via standard RESTful operations and subscription to business events. The model expresses the distillation of the core domain and conceptual contours to achieve a balance of composability and cohesion.
Composability and cohesion are discussed in more detail here.Security By Design
In a process of model driven design the capability development pipeline is vertical, and security is embedded into every stage of the process.
Data is classified and regulatory controls identified during the domain modelling phase. Data handling and security controls are implemented accordingly by the business service responsible for the data. DevOps automation will validate API management security controls against a pre-configured set of security policies and schemes, and automated security testing is incorporated into CI/CD pipelines. Client onboarding and API subscription via API developer portals may be validated and authorized.
Sensitive APIs are secured by OAuth2/OIDC, and documented security definitions are enforced at the gateway. API management and event message platform integration into analytics driven Security Incident and Event Management (SIEM) platforms is essential. Event tracing provides detailed incident data and valuable insights into interconnected systems.
Security-by-design is discussed in more detail here.Anti-Corruption Layer
Systems operating across multiple domain boundaries “must be prepared for gradual and fragmented change, where old and new implementations co-exist… the architecture as a whole must be designed to ease the deployment of architectural elements in a partial, iterative fashion” — Fielding, R.T. 2000, Designing the Web Architecture: Problems and Insights.
The application of an anti-corruption layer will enable a legacy or proprietary capability to expose discoverable, domain aligned, enterprise consistent interfaces to business data, and to consume APIs and events published by other business capabilities. An anti-corruption layer might be as simple and tactical as a mediating façade, or as comprehensive and strategic as decomposed component services managing replicated data.
Business Events
Domain business events are the asynchronous compliment to synchronous REST interfaces, and align with the state-lifecycle events identified during the Domain Driven Design process. Each System-of-Record business resource will emit real-time update and state-lifecycle transition event messages that constitute the definitive log of temporal events.
Like a resource API, event messages are an abstraction that do not expose internal database schemas across domains. For the sake of intelligibility and manageability, business events and APIs would express a common model.
Federated Data Platform and Downstream Analytics
System-of-Record REST models that clearly express and expose composable, filterable aggregates within the domain, and an enterprise log of temporal business events provide the foundations of a discoverable, decoupled, secure and scalable federated data platform. “Source domain datasets represent closely the raw data at the point of creation and are not fitted or modelled for a particular consumer. Data consumers can always go back to the business facts and create new aggregations or projections.” — The Open Group 2019, Open Agile Architecture.
Aggregated temporal views are constructed from source-of-truth representations and event metadata. Analytics platforms are downstream, non-blocking consumers of business data.
Level 3 — Domain Model Driven Development and a Harmonized Interoperability Framework
A well-defined process and complimentary tooling to enable model driven development and vertically integrated DevOps is required to reduce (the often considerable) friction between development, implementation and delivery of the model.
Model Driven Development
A domain modelling platform must enable all stakeholders, from business owners, enterprise and domain architects, security architects, platform SMEs, tech leads and developers, to interact with (and contribute to) the same domain data model in context, and to be notified of changes that interest them.
Ideally, modelling tools will generate OpenAPI specifications directly from the domain model, support source control, and manage semantic versioning across the model and its derivative artefacts — features that are helpful in maintaining the currency and traceability of published APIs.
Vertically Integrated DevOps
As managed APIs are the interface to deployed microservices, DevOps tooling must ensure that new and updated interfaces and schemas are published to API management and event platforms simultaneously with the deployment of business services. Deployment and testing of APIs must be automated, domain-autonomous and as frictionless as possible.
DevOps pipelines will apply Policy-as-Code controls and enforce mandatory standards with specification document linting. Global API security testing and continuous testing of security controls applicable to each business API is built into integration and delivery pipelines and regression tests.
Managing API Lifecycles with Model Driven, Integrated DevOps is discussed in more detail here.A Harmonized Interoperability Framework
REST API, affordance, HATEOAS, business event and data-as-a-product models are coordinated around the same authoritative domain business information resource model. The business resource model captures not only operational entities and value objects, but also the state lifecycle and temporal analytical models.
At an operational level, an Interoperability Framework will seize opportunities to streamline and align protocols, interfaces, analytics, access control and workflow management across heterogeneous API management, event messaging and security platforms.
Harmonized Business Events
Business events are intrinsically bound to the REST model. An event message may be the entirety of, or delta to the current representation of a business resource per W3C Websub or a REST aligned AsyncAPI schema, or it may simply be a notification that the resource has changed with a link back to the REST API as the source of the current state of the resource, as per the secure ‘claim-check’ pattern.
A subscription portal/hub will support programmatic and dynamic subscription to events on a resource instance granularity.
Harmonized Business Events are discussed in more detail here.HATEOAS and Affordances
In a minimum-viable implementation as part of a harmonized framework, every HATEOAS link is keyed to a documented state-lifecycle transition affordance operation, and successful invocation of the affordance would result in a state transition and a published business event.
The name of every HATEOAS link will correspond to a documented operation with an explicitly defined request and response document, referring to an operationId or to an OAS 3 link name.
HATEOAS, affordance and event alignment are explored here.API Enabled Data-as-a-Product
Data Mesh principles as articulated by Zhamak Dehghani (Thoughtworks) extend and evolve the Federated Data Platform concept, placing responsibility for domain-relevant temporal views with domain experts at the System of Record. Enterprise distributed query and analytics platforms are responsible for the experience layer and for the composition of esoteric and cross-domain temporal views.
GraphQL is a good fit for this use-case, and has the potential to leverage and extend existing API management infrastructure and governance.
Security Platform Integration
A zero-trust posture and mandatory OAuth2/OIDC token requirement by API gateways and resource services can provide defense-in-depth and help align API and event access management with an organization’s security posture and policies.
OAuth2/OIDC schemes and scopes will be applied to APIs at an operation granularity to provide API owners with a mechanism to control the scope of client application access to their APIs.
A shared, single point of entry process for organisation and client system on-boarding for IAM and API Management platforms provides an optimal client experience, reduces duplication of effort and ensures synchronicity between platforms.
API gateways and API providers will log authorization/access events to Security Incident and Event Management (SIEM). The cyber security team maintains and evolves solutions leveraging increasingly sophisticated AI tools to detect, investigate and respond to abnormal invocation patterns and user behavior. Security and API gateway platforms will provide affordances to SIEM for active threat protection.
Security Platform Integration is discussed in more detail here.Summary
Agreement on an intentional API maturity model can underpin coherent and evolvable API and interoperability standards, identify intermediate and target states, and minimize technical debt.
We have outlined an API Interoperability Maturity Model concerned primarily with the interoperability qualities of APIs, and in which is embedded the common contemporary constraint of an enterprise managed API capability based on an API specification standard. The model underpins the importance of standards and patterns, DDD derived business resources, security by design, business events, model driven development, integrated platforms and vertically integrated DevOps, in achieving domain alignment, decoupling and agility.
Related Discussions on Medium
API Design Practice. A practical guide to API QA
Writing API Design Standards. An 8-step guide
Securing APIs with an Integrated Security Framework
The Engine of Application State. Aligning HATEOAS, Affordances and Business Events
Evolving API Management into a Harmonized API-led Interoperability Framework
