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?

Here’s a quickie video describing the application layers of a RestExpress application when one of the Maven Archetypes is used to create a new RestExpress project.

http://youtu.be/ZFqjvNiB-hY

To summarize: Visibility or “awareness” goes down. Meaning that a layer can call (or know about) the layer immediately below it, but an application layer cannot call the layer above it or a layer deeper than the next immediately lower. In other words, if there’s database orchestration code in the Service Layer or Controller, that’s poor design. And conversely, if there’s HTTP header, request or response manipulation in the ServiceLayer or Persistence Layer, that’d be bad.

Layer #1: Controller/HTTP Layer

HTTP layer where requests, headers and responses are manipulated and processed.
Handles serialization of request body to domain model.
And deserialization from domain model to response.
Makes call to only the Service Layer (layer #2).

Layer #2: Service Layer

Business logic.
Calls methods on domain model to orchestrate business logic and domain functionality.
Calls Persistence Layer to store and read domain model instances.
Returns domain model instances to the Controller/ HTTP Layer.

Layer #3: Persistence Layer

Sometimes call DAL (data access layer) or DAO (data accessor object).
Called Repository by Eric Evans in his Domain Driven Design (DDD) book.
Creates an interface to perform queries and database operations.
“Serializes” and “deserializes” domain model instances to/from the database.

Month: October 2014

“Experience API” defines Every API