Translating The World Of Hypermedia APIs For The Normals

I’m giving my hypermedia API research a little love today, and as part of this I was reviewing examples of hypermedia in the wild like with the Elastic Path Cortex API. Elastic Path was the first company to introduce me to the possibilities around hypermedia way back in 2011, so I enjoy checking in regularly to see what they are up to with their APIs.

As of January 2014 I’ve committed more time to doing research on hypermedia APIs, as well as work to tell stories about how hypermedia is being applied by companies, in a way that anyone can understand. This last summer at API-Craft in Detroit, the hypermedia community acknowledged that they have an image problem, and had some significant work ahead of them when it comes to storytelling, specifically around speaking to the “normals”.

Personally, I don’t 100% speak hypermedia-eze, but I know with some practice I can get better at translating. I also know that some of the hypermedia folks aren’t so good at speaking plain english to normal people, but with some practice I htink they will also get better. To help me in my jouney I figured I’d translate what Elastic Path has written on their Cortex API page, but first I want to acknowledge the image they have--which is the first sophisticated hypermedia visual I’ve seen, and I want to work on creating more like it.

Let’s get on with the translation from hypermedia-eze to plain english. Elastic Path starts with:

Cortex is a mediation layer that uses patent-pending dynamic linking technology to discover and assemble resources from multiple business platforms into one consistent interface. Data and services from enterprise applications like Commerce Engine, Adobe® Experience Manager, OpenText® CEM, and others are mapped to Cortex using a lightweight schema. Once abstracted, these resources — from any source — are linked together to generate Cortex Business APIs that securely project your unified services to the world.

Translation: Cortex brings together all your information, no matter where it resides, into a single, consistent API that you can then securely share with anyone you desire.

Cortex mediation completely decouples client applications from business platforms, yet enhances their ability to securely retrieve data and perform transactions. This breakthrough hyper media approach gives designers, developers, and API consumers the unprecedented freedom they need to create unique digital experiences — from mobile apps to Internet Retailer® Top 500 websites — that engage customers and create business value.

Translation: Cortex understands that you are delivering information to a wide assortment of web, mobile and tablet devices in 2014, and Cortex handles the heavy load, abstracting away the complexity for API developers, allowing them deliver more meaningful experiences for end-users, agnostic of any platform they use.

A hypermedia API means self-serve e-commerce.

Translation: A hypermedia API means self-serve e-commerce.

Unified services from your application portfolio are exposed via Cortex Business APIs, a set of highly scalable REST interfaces that conform rigorously to the HATEOAS constraint and Level 3 of the Richardson Maturity Model. This means that client applications can securely access enterprise data and perform authorized operations using only the hypermedia controls generated by the mediation layer. No deeper knowledge of your business platforms is required — so the tyranny of constant integration work ends with Cortex. It's simply the best API for ecommerce platforms.

Translation: Similar to understanding all of the devices you will be delivering information to, Cortex understand which users are accessing your information, and securely delivers only the information they have access to, and enables them to only take the actions they have afforded to them, again abstracting away the complexity of business operations for developers.

My translations may not be perfect, but in short, because the they employ hypermedia design patterns, the Cortex API can more intelligently consider which internal, or external systems your information is being pulled from, while also understanding the context of the end-user who will be accessing this information, both who they are, and what device(s) they are using, potentially handling all of this logic for developers, leaving them to do what they do best.

You see, APIs have been abstracting away the complexity of back-end system for a while now, but hypermedia has the potential to abstract away a couple more of the key layers for developers--who the user is, and what device (channel) they are engaging upon. When done right, this has the potential to make the delivery of digital resources via APIs, to any number of online channels much more streamlined and efficient for everyone involved.

Of course, even though all of this is a reality with Elastic Path right now, we have huge hurdles to jump in helping resource owners, and application developers understand the benefits hypermedia can bring to their operations, and this is why I'm honing my hypermedia translation and storytelling skills so I can help be a conduit in these ongoing discussions.