Building APIs at the high standard is challenging.
While many people would argue they are doing APIs, they are simply exposing basic read and write operations in a CRUD mode.
Quality Engineering APIs are much more than that, enabling business growth with an increased composability leveraging modularity.
This article focuses on the three pillars of APIs that are game-changer for businesses to accelerate their digital transformation.
Follow the QE Unit for more Quality Engineering.
How Quality Engineering provides Composability
Quality Engineering is the paradigm constraining the entire software lifecycle to continuously deliver value through Quality at Speed software. Its implementation relies on the MAMOS framework acting on the 5 domains of Methods, Architecture, Management, Organization and Skills.
The Architecture domain provides technology composability through progressive and concrete practices building upon the foundations of a Quality Engineering Structure and Quality Engineering Modularity, both necessary to accelerate composability.
While well-defined software modules provide the behavior change flexibility, the main challenge is to make services easy to integrate and use for multiple actors of today and tomorrow. The architecture and exposition of services through technology is the important matter for composability.
Technical solutions available to interconnect systems are ranging from files to service calls through defined protocols. A progressive Quality Engineering composability focuses on standard mechanisms widely deployed in the ecosystem based on proper REST APIs.
Quality Engineering Microservices relies on these 3 architecture practices:
- API-driven components
- API-layers architecture
- API-composable technology.
API-driven components: composability by design
Components that can talk to each other with minimal effort require an end-to-end alignment of technology starting from the design phase. Integrating “composability by design” drastically eases the integration and evolution of software in the long-run.
Composable components share the following API-driven traits:
- Contract-first
- Abstraction
- Specialization.
Contract-first
Contract-first represents the “design-first” philosophy of API-driven software components that starts by defining the interfaces between the producer and consumers. The goal is to maximize the value created by APIs with short-cycles of iteration with minimal commitment and effort.
The process is the same as for mockups before coding a user interface: an early collaboration on the contract, teams including partners enable them to perform early validation of the API without even having performed the concrete software development.
This focus also enforces to focus on the expected value and interactions instead of the underlying implementation details. In the end, contracts are aligned on the use-cases to streamline integrations and improve the API abstraction.
Abstraction
Organizations that want to collaborate have different backgrounds. Their business domains are different, as well as their vocabulary or services, that’s in fact where their complementarity is. But the gaps all increase the time-to-market and complexity of interconnecting services.
Providing an abstraction layer over the technical implementation is a common industry practice to remove the technological gap between companies. The REST API standard is one of the most used nowadays to simplify the integration of API-driven software components.
Specific sectors benefit from an additional layer of abstraction through shared interface standards. One transversal example is the use of EDI standard with US/EDIFACT for trades sharing in the United States. More recent examples are appearing and could be game-changers in industries.
Specialization
Things that tend to do everything end up doing anything. Accumulating complexity in a single point leads to a level of entropy that is too important to be manageable. That can quickly happen with API-driven software components exposed to multiple consumers.
Organizations have to be very strict on their API catalog and policy to keep a “high cohesion and low coupling” of their services. Governance is required here as the accumulated complexity usually results from too much reuse with small changes that adds-up over time.
Maintaining the specialization of components is a requirement that can be best ensured at a local level by a counter-force acting at the global level, with the big picture. That’s where an API-layered architecture can help to build API-driven components with “composability by urbanization”.
API-layers architecture: composability by urbanization
We can think that all APIs are equals when everyone is talking about “APIs” in a generic way. But specialized APIs have been built to solve a defined set of problems, in a specific context, and for or a range of users enabling to improve their composability.
The first perspective to define APIs is at which layer they are acting. APIs supporting the user experience or internal business processes have a different positioning within the architecture; the first one acts between users and internal users, and the other ones on top of multiple services.
The second perspective is the typology of the APIs that depends on the functions they are providing. Some APIs are urbanized to solve an orchestration problem, others to provide a federated view of multiple data facets, others to perform unitary business functions.
The resulting combinations of urbanized APIs layers and typologies are:
- Experience APIs considered as “Layer III – APIs”
- Process APIs considered as “Layer II – APIs”
- Systems APIs considered as “Layer I – APIs”.
Experience APIs
Services built to support experiences solve the problem of easing the composability between external users and internal services. Trying to accommodate the missing parts on each side would accumulate too much complexity that would result in an inability to evolve systems later on.
“Experience APIs” are therefore built to solve the intermediation layer and must follow strong guidelines to keep their focus. The general principle is to solve integration problems that are not presentation concerns on one hand, not internal business functions on the other hands.
The presentation layer is responsible for providing successful user interactions over different channels and ensures its session is maintained. This layer must not contain any internal business functions or rules to offer scalable omnichannel experiences supported by process APIs.
The following APIs experience layers have to clearly identify its consumers and producers to define which problems are best handled in these APIs. A traditional example is to handle the e-commerce basket lifecycle being possibly linked to multiple channels, but still not being a back order.
Downstream layers after the presentation and APIs experience ones are responsible to perform back-end and internal business operations functions. Any functions falling in that category must not be performed in the experience APIs to avoid creating a spaghetti architecture.
Process APIs
Right now you may ask: why bother with an additional layer after covering the presentation and experience layers? Why back-end services cannot directly perform the different functions and rules we need for these top-presentation layers?
The answer lies in the initial requirement of composable technologies that must provide a contract-first abstraction and specialization. Let’s take the example of placing an order in a distributed architecture where there’s no process APIs.
The ordering process requires the collaboration of multiple systems: stock must be validated, delivery address quotes by the transporteur, the payment must be checked, among other criteria. Without a process APIs, either an Experience APIs or the order management API become a monster.
That’s where building process APIs help to isolate the complexity with abstraction and specialization. A dedicated ordering process API can be built on top of stock, shipping, payment and other APIs to isolate the mechanisms of validation across systems without handling the internal complexity.
Process APIs are exactly built to solve the missing link between presentation and dedicated business services that were not built to discuss together. First implementation can be made through synchronous orchestrated APIs call, but are preferable to evolve as choreography.
System APIs
The layer I APIs, or “System APIs”, are the ones responsible to expose unitary business functions through abstracted and specialized services. A common practice is to build this APIs layer with modern technology to accelerate composability over legacy or modern services.
System APIs must exclusively focus on solving the exposition of a business function through an explicit interface. It must not handle any concerns of the presentation, experience or process layers to maximize its composability and evolutivity.
Even if these APIs seem trivial, they are usually bypassed by teams rushing into their digital transformation. Experience, Process APIs or a mix of them are then built into single components that support first use-cases but that quickly reaches limitations.
Systems APIs are therefore fundamental expositions to address early in transformation based on the Quality Engineering Structure and Modularity that identified the core business services to provide as part of the urbanization.
API-composable technology: composability by connectors
Once APIs have been correctly designed and urbanized, we can start talking about the technological implementation. The Quality Engineering counter-force remains present to ensure this stage is not a mere coding stage of specifications but true quality engineered APIs.
API-composable software components require the combination of technology that improve the connectability of APIs through its lifecycle. It starts by building APIs aligned with the contract-first mindset to then leverage technology to accelerate the deployment of APIs in the ecosystem.
Composable APIs shares the following technology traits:
- Headless
- Open standards
- Self-descriptive.
Headless
Software components that decouples the front end (i.e. the “head”) from the back-end (i.e. the “body”) are called headless. The main advantage is to increase the API abstraction and reuse to support much more “heads”, that are in the end, more paying consumers or users of the APIs.
The headless trait is one implementation of the abstraction and specialization principles. By making sure APIs are not linked to one specific front-end, the composability of the service increases for any consumers that can benefit from the specific services exposed by the APIs.
A concrete example that spread is “Headless CMS”. Previous content management systems were directly tied to a web user interface and lacked scalability with the advent of mobile applications and the need to share content over multiple channels like comparators or social media.
Headless CMS focuses exclusively on content management removing the presentation functions from their implementation. The results are leaner components able to answer much better to the content management challenges with a drastic increase in composability over multiple channels.
Open standards
The technical languages and dictionary of exchanges has been a war in the ecosystem. Different providers and industry consortiums tried to push SOAP that ended up as a failure with multiple standards pushed by different companies, and a quite verbose language.
REST has been a game-changer for increasing the composability of services gaining momentum in the industry. Its simplicity and unified format adopted in the ecosystem makes it a de-facto standard as of today, mainly relying on its REST/JSON format over other alternatives.
While REST describes a uniform exchange interface of resources, it is not a business dictionary or format standards. That’s where openAPI and asyncAPI took their place to define an open format to describe composable APIs adding up to the composability of services.
Building REST/JSON APIs that expose their contract-driven interfaces through these standards is a true accelerator for companies. The explanation, integration guide and even automated code generated can be generated just by exposing services with these technologies.
Self-descriptive
Deploying APIs at scale with multiple partners can be achieved with maximum automation. The main limiting factors for adopting APIs being the explanation and support, solutions that enable partners to integrate APIs in self-service significantly improves composability.
Swagger is the first element of self-descriptive APIs. This standard provides a user interface that builds upon the standards asyncAPI or openAPI previously shared. Its main value is to provide interactive documentation that can be leveraged by multiple partners to scale.
But we can do even-better for self-service.
HATEOAS stands for Hypermedia as the Engine of Application State. It is a constraint of the REST application architecture that lets users dynamically navigate APIs like we are used to with web interfaces, clicking from links to links to discover other websites, described in the RFC 5988.
A major achievement of HATEOAS is to provide few entry points to business services to then let users browse available services at their own convenience. This is the maximum composability that can be achieved through technology, requiring a strong degree of Quality Engineering.
Composable APIs to thrive with Quality Engineering
A gradual approach to the Quality Engineering traits of composable APIs is required to incrementally deliver value. The work must start on the most valuable APIs first ensuring the end-to-end alignment, putting aside HATEOAS in the backlog in the first increments.
This article focused extensively on REST components being the most widely used in the ecosystem and the ones to start with. The shared frame of reference can be applied to other technologies like graphQL or gRPC keeping the same principles like abstraction and specialialization.
The success of composable APIs is first measured in the business growth generated through APIs like new digital offerings, internal business adaptation, or channel expansions all supported by components that are highly reliable and fast to evolve.
Composable businesses are the one who will survive the digital transformation leveraging composable software assets. These organizations will be able to rapidly adapt their value proposition with reactivity, while the others will be failing at integrating a few partners for months.
Don’t lose time, and start building for composability.
References
Dimuthu Leelarathn, Contract-First Design. WS02.
Jim Barton, Roman Martin. Contract-First Development, Open Practice Library.
Janet Wagner, Understanding the API-First Approach to Building Products. Swagger.
Danijel Dragicevic, Compose your business platform using the API-led connectivity approach. Code Centric.
Rafael Rocha, 7 Layers of API Architecture Maturity. APIScene.
Brent Heslop, Having an API Doesn’t Make Your CMS Headless. Content Stack.
Lokesh Gupta, HATEOAS Driven REST APIs. RESTFulAPI.net.