Monday, July 30, 2018

Hello HAL, Welcome to Cortex!

Back in 2011, Elastic Path decided our future was in Headless Commerce, and to succeed we needed to offer the best API experience possible. Our journey started with a clean whiteboard, a green field and plenty of time for research and discovery. What would our customers need? How would their shoppers connect to this API? What would be the best way to communicate a dynamic, flexible commerce journey across multiple touchpoints? This was at a time when people watched Netflix from their XBox and Facebook was just a website. The Internet was a desktop browser and people still called each other on their smart phones.

After various experiments with SOAP, RPC and other API patterns, we committed to Hypermedia REST, or what was called HATEOAS back then. We chose Hypermedia because it delivers three key advantages, all from the same core aspect--linking.

First off, linking gives an API discoverability. Much like browsing a website, a linked API gives the developer a way to find how the services fit together. Rather than knitting separate concepts in their head, they are shown the relationships in the API itself. Imagine browsing a website without links. That's what it feels like to access an API that doesn't provide links between the services.

Second, linking gives the API extensibility. Commerce is a complicated business, and the customers who buy Elastic Path succeed because of their unique selling propositions. They want their uniqueness to come out through the experiences they deliver to their shoppers. Links blend this uniqueness with our commerce services and project a seamless API for their developers to discover and use in the experiences they build.
Third, linking provides an API with long-term stability. Links define relationships between services, and one thing people are really good at is identifying and describing relationships. These linked relationships are traversed by the clients, and because the links are stable, those clients are stable too. In 7 years we have never had to change a relationship, though the API itself has expanded tremendously.

Linked APIs fit our requirements nicely, yet when we looked in the market for technology, we found little support for building Hypermedia APIs. Open Source had nothing. Commercial offerings were also unavailable. People were talking about HATEOAS, but no one had seen a significant implementation, much less one at an enterprise scale. Most importantly, no established standards were mature enough to guide us, though work had been put forth by engineers at Apigee and some Semantic Web refugees. We were going to have to do it alone.

Convinced of the correctness of our approach we built Cortex, Elastic Path's API platform and bound it to our core commerce logic. We developed a simple JSON format for communicating the linked relationships, a developer framework to bring resources to life and the engine to link them together. Cortex was our starship to the future, hand-built by idealists with decades of enterprise-grade software development experience.

Fast-forward to today and the world is quite different. Facebook is mobile-first, headless commerce is what enterprises are transitioning to, and linked APIs are becoming mainstream. We look at the API we built with Cortex and find much of what we have is tremendously valuable to our customers, but one thing has to change.

In the last seven years a Hypermedia standard has emerged for the content part of the API. That standard is HAL (Hypertext Application Language). We see HAL in important places like the TM Forum, which uses HAL to describe relationships in their APIs. Wordpress uses the HAL standard for their content APIs. Dozens of open-source projects support HAL in a wide variety of environments (Eiffel HAL, anyone?). HAL is not the only standard out there, and some have more noise in the market these days, but for our business we have decided to deliver HAL.

HAL fits with Cortex very well and we can continue to innovate with HAL as an API format. Our Studio tooling and zoom querying technology support HAL as well as our existing format. Every Resource developed in Cortex over the last 7 years is accessible from the HAL media type. With HAL, you will benefit from all Cortex has to offer, but in a standard format. Our customers want this standard API response format to drive their customer experiences with open-source client technologies using patterns like Progressive Web Application (PWA).

So, as of Elastic Path Commerce 7.3 release, your client developers can ask for their API with Content-Type: "application/hal+json" and start consuming Elastic Path Commerce via HAL, with any one of the many open-source clients built for your choice of technology.

Hello HAL, Welcome to Cortex!

Back in 2011, Elastic Path decided our future was in Headless Commerce, and to succeed we needed to offer the best API experience possible....