February, 2014 | digitalML
Canonical Models Should Be A Core Component Of Your API Strategy Reading Time: 3 minutes

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:

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:

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:

diagram showing API Facade Mapping

API Facade Mapping

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.