Daniel Jacobson, Director of Engineering – Netflix API, uses some terms in his post, The future of API design: The orchestration layer, that are making things difficult for those of us trying to communicate in the API space.  Specifically,  the two terms, “API Orchestration Layer” and “Experience API.”  These are neither accurate nor meaningful.  Let me explain…

API Orchestration Layer

From Daniel’s post:

An API Orchestration Layer (OL) is an abstraction layer that takes generically-modeled data elements and/or features and prepares them in a more specific way for a targeted developer or application

This concept is describing an Aggregation Layer, not an orchestration layer.  Per the almighty, always-true, Wikipedia:

Orchestration describes the automated arrangement, coordination, and management of complex computer systems, middleware, and services.

An orchestration layer determines order and sequence, orchestrating events and sequencing of messages in a service-oriented architecture.  On the other hand, an aggregation layer performs operations and data transformation to provide a specific payload for a specific client.  Both are useful, but don’t confuse the two.

Let’s talk about aggregation where we mean aggregation and orchestration where we mean orchestration.

Experience APIs

There is no such distinction. Nor should there be. Let me be clear: Every API is an experience API!

Make no mistake, no matter whether you’re targeting internal develops, third-party integrators or public developers, those folks have an experience with your API (good or otherwise).  However, now I’m hearing businesses talking about how they don’t need to design their RESTful APIs, since they’re just going to put an “experience API” on top of it.  Please stop using the term.

Appropriate alternatives are: Public API, Internal API, Crappy API, REST API, etc.

In Short

APIs are the new and shiny thing that businesses are currently chasing for the sake of being part of the so-called “API economy.”  Understanding is important. APIs are confusing enough without using a ubiquitous language to describe what we mean.  Can we agree to use accurate terms?