Using a canonical model for data in motion through Web (SOA) services means you’re following the widely adopted and successful canonical schema design pattern . But even in the fast-moving and rapidly evolving world of APIs (most often REST style, often with JSON payloads), it’s no less important to include canonicalization in your strategy.
Why? On the simplest level, the case for canonical models for APIs stems from the “R” in REST, which stands for Resource. A Resource is often synonymous with an Entity (e.g. Customer, Product) – so in designing a set of APIs, one of the most important things to get right is the structure of the data, the resources, the APIs will operate upon. However, that answer is a bit too simplistic for anyone who has actually worked with APIs, as there is such a wide range of API types, including:
- App-specific APIs, often for mobile or OmniChannel apps, that reflect the design, capabilities, and workflow of their apps, and the devices on which they run. These are sometimes called “consumption” APIs, and their data model is usually driven more by the model of the consuming application than the canonical.
- APIs that encapsulate widely used back-end data or functions, which are sometimes called “exposure” APIs, as they expose canonical resources.
- Services that implement the API façade pattern (which may indeed map consumption APIs to exposure APIs, or even to a set of complex legacy application interfaces).
- Internal APIs vs external APIs, which may be mandated to follow the same architecture guidelines (as per Amazon). Either can be a consumption or an exposure API, depending on the situation.
- APIs primarily designed to expose content/information (as REST resources), such as the NPR API. These often reflect a canonical model of information.
Across this wide range of use cases and business contexts, the case for a canonical model varies widely. The canonical approach is most relevant to exposure APIs, the API façade pattern, external APIs consumed by partners who agree a common exchange model, and information-centric APIs. Of course, REST purists would argue that all APIs should be information (resource) centric, but as pragmatic REST is more popular, one sometimes encounters resources that break this rule.
But even when an API falls outside the “sweet spot” for a canonical model, if it is part of a portfolio with other APIs that expose canonical elements and attributes, there’s a strong case for loose coupling of that API to the canonical, so that:
- Where the API exposes information that’s in the canonical model, it maps to the canonical representation, naming, and semantics. Failing to do this just introduces needless complexity and confusion. Mapping to canonical elements and attributes doesn’t mean the API must use those names – it can choose to expose them through simpler names such as “ID,” as long as we know which ID it is, in the tools we use to manage the API design.
- Where the API has its own information local to its implementation, it handles that as local elements and attributes. Model managers can periodically review these to determine whether to evolve the canonical, but if the data is specific to the local context, may well decide not to include it in the canonical.
- As the API portfolio evolves, IT has good visibility into data lineage and the impact of change across data sources, services, and API operations. It’s only through capturing these links as a natural side-effect of developing and delivering APIs and the apps that use them, that digital firms of any size can hope to cost-effectively sustain their digital business.
Managing these mappings is best handled with the aid of powerful tools like the ignite platform from digitalML, which helps you define the canonical, speed API delivery, and manage the evolution of both. Without tools, knowledge of these mappings fades with time, and it’s hard to trace data lineage. ignite supports this approach through a simple process of trimming canonical message formats, while maintaining the mapping back to the canonical model (which in turn is also mapped through ignite to provider systems). We can depict this as:
Without the right tools to assist teams in rapidly delivering APIs while aligning with a canonical model, these practices may prove so labor intensive that deadline-driven teams choose a more expedient path. The cost? A faster buildup of technical debt, as multiple disparate API implementations lead to API chaos, limiting reuse while enlarging the cost and size of the service portfolio, with little corresponding benefit in added API capabilities.
Leading firms in retail, telecom, banking, insurance, and other industries facing digital disruption are using the ignite platform to automate and speed API delivery while aligning with a canonical model. The automation ignite provides makes it practical to use the canonical schema design pattern to speed and govern delivery of your API and service portfolio. Get started today, and you’ll find that you can deliver more APIs more quickly, while reducing the overall number of APIs you need, and lowering the cost of maintaining your API portfolio.
Learn more about how ignite supports managing an enterprise API porfolio in a standardized way in this free whitepaper:
