Managing API Lifecycles with Model Driven, Integrated DevOps
Reducing friction between model development and delivery
API enabled, interoperable business services often endure considerable friction and blocking engagements coordinating the delivery of new and updated interfaces. A well-defined process of model driven development, complimentary tooling and vertically integrated DevOps can substantially reduce friction between domain model development and delivery.
Model Driven Design
A Domain Model, the product of a guided API design practice, is the source of truth for the business capability implementation and the REST model, and “acts as a Ubiquitous Language to help communication between software developers and domain experts” (Fowler, M 2014, BoundedContext)
A process of Model Driven Design is ‘model driven’, however it is not ‘model up-front’. Domain driven design must be an iterative process — the model must learn from the realities of implementation and must be rigorously maintained in order to capture and communicate the evolution of the model.
API Design Practice is outlined in more detail hereDesign Tooling
A collaborative domain modeling platform will allow all participants, from business owners, enterprise and domain architects, data modelers, security architects, REST and EDA 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.
API specifications are generated from the model, in conformance with API standards and security policies. These may be tool generated based on standards and policy-conformant rules or templates.
A number of modeling tools will generate OpenAPI/Swagger API specifications directly from the domain model (although ease-of-use varies widely). Less common is support for source control, and management semantic versioning across the model and its derivative artefacts — features that are helpful in maintaining the currency and traceability of published APIs. Alternatively, API modelers will create the specification based on the model, in conformance with API standards and security policies.
Other domain modeling platform features strongly supportive of model driven development include:
- Model validation
- Support for meaningful documentation of state-lifecycles, e.g. state-lifecycle diagrams
- Mapping and management of external dependencies, including notification management
- Model discoverability, sharing and re-use
API versioning strategies are covered in more detail hereVertically Integrated DevOps
Source Control & Code Integration
API specification documents would ideally be co-located in a repository with the service implementation.
Continuous integration pipelines should enforce mandatory standards with API specification linting, analyse test coverage, and validate API security schemes and policy configuration. OpenAPI document linting rules should be clearly defined. Spectral OpenAPI rules are widely referenced as a base OpenAPI document ruleset.
An API build & delivery process will ordinarily be built and maintained by the API platform team for integration into product team pipelines. It may be that API document paths are passed to triggered API build & delivery pipelines, or alternatively, in a ‘plugin’ module based approach, there may be a convention that dictates the path to API specification documents and/or a configuration file in the repository for CI-CD purposes. The detail may differ depending on the technology stack, (e.g maven vs npm project structure).
API document rules and validation are covered in more detail hereCoordinated, Automated Deployment
Microservices architectures are “built around business capabilities and independently deployable by fully automated deployment machinery. There is a bare minimum of centralized management of these services” — Microservices (martinfowler.com).
‘Code-first’ automation is a significant component of a mature API management capability, and is enabled by APIM platforms that expose their own management APIs to automation.
As managed APIs are the interface to deployed microservices, DevOps tooling must ensure that new and updated interfaces and schemas generated by domain modeling tooling and implemented by a business service are published to relevant API management (and potentially event, security and distributed graph) platforms simultaneously with the deployment of the business service. Deployment and testing of APIs must be automated, domain-autonomous and as frictionless as possible.
When new versions of an API are deployed, automation must be able to detect and deprecate previous versions (no new subscribers).
CI/CD
Access to a sandpit and/or Dev environment should present a low barrier, allowing teams to experiment rapidly. Occasionally APIs may be deployed early to a dev environment back-ended by a mock service to unblock client applications.
API delivery to higher environments via autonomous CI-CD pipelines will sometimes involve tighter governance and accountability. Delivery pipelines may be white-listed for promotion through environments — onboarded and certified by release management or a DevOps platform team. Full test coverage will be expected.
Testing
Automated Testing
Full coverage delivery pipeline test scripts must be built and run following delivery into each test environment in order to provide consistent, repeatable testing of API methods and the complete resource state-lifecycle. Responsiveness, scalability and reliability should be evaluated and benchmarked with performance testing.
Continuous Security Testing
Global API security testing targeting known risks and vulnerabilities (incl. OWASP top 10) should be overseen by Cyber-Security specialists and routinely reviewed and maintained. Continuous testing of security controls applicable to each business API is a delivery team responsibility and is built into integration and delivery pipelines and regression tests.
Testing Platforms
Enterprise testing requirements, tools and platform guidance should be provided to developers, together with detailed tool and platform-specific documentation and ‘getting started’ resources.
API testing is covered in more detail hereWrap-up
A well-defined, tool-supported process of Model Driven Development, Vertically Integrated DevOps and Continuous Security Testing will serve to ensure robust, secure APIs of a consistent quality, streamline delivery, provide early feedback on document and configuration issues, and minimize blocking engagements with centralized API management team and processes.
