Towards a progressive REST API model

"Although REST interaction is two-way, the large-grain data flows of hypermedia interaction can each be processed like a data-flow network, with filter components selectively applied to the data stream in order to transform the content as it passes"

Roy Fielding's dissertation

This is the last post of my 5-piece API story "You don't manage the API, the API manages you". In my first real full-time job in a startup, founded around 2004, I had the role of both CIO and CMO. Back then, outsiders were not only laughing at this combination, but investors directly took is an example why the organization would be immature and not able to survive. It did, though, and prospered for a long time. Fast forward 10 years later and McKinsey, Deloitte, Accenture and Adobe are promoting the CIO/CMO model and more, design thinking as culture and blueprint. And CMO/CFO get closer with programmatic content and advertising. From my own experience in startups, but also consulting and service design, I know this model is not only about making the company customer-centric, and product-centric, but focusing the culture on most value [outcomes] instead of cost savings. It's about having a common goal, and allowing fast feedback for the product or service of the organization. This fast feedback requires fast, agile changes, a lean cycle, a risk culture and a real collaborative service, or product, design - I don't like singularity but it seems that cybernetics has won.

What does that mean for our API's? Can we really still revolve around a relatively static* hyperlink model that does not embody this feedback?


*) I am aware of solutions to that, like Gateway API's, Content Negotiation and Redirects but the core issue of no common ontology still exists and DDD alone cannot solve this

Caching means Retention and other Web API quirks

"Fun here becomes related to formal logic and repetition, to the question of where software starts and ends, to mental states, to what operations it can carry out on the world, to the cultures and usages of software, to its building upon itself, to its aesthetics"
Olga Goriunova

For everyone who the other 3 posts in this series were to philosophical, relax, this is a technical one.

Thanks Daniel for suggesting Vinay Sahni's "Best Practices for Designing a Pragmatic RESTful API"; I like that he also emphasizes on documentation, what works in the real world and still believes in some principles like links. Also, Pedro's "List of HTTP API Specs", thanks to Mike for this tweet. And of course the ubiquitous REST Cookbook and the always good Apigee guides (I would reference CA Layer 7 here as well but they hide their guides behind a spamwall), the pragmatic API blog and Steve's rant.

As the 2nd last piece in this series, let's have a look into some technical quirks of Web API's.

The API and the Stream

As Alexander mentions in pattern No. 110:

“The position of main entrances controls the layout of the building. It controls movement to and from the building, and all the other decisions about layout flow from this decision. […] the first step in placing the entrances is to consider the mainlines of approach to the site”

In my last post I have written about API's as portals into your systems, a kind of grey box that gives enough semantics away to understand your system, but abstracts it for the target user group. While there is a lot material about patterns within API's and when to use API's (in messages/services), about the good and the bad, I still miss a holistic picture of systems-of-systems architecture that focuses on the API as the service itself. A behaviour that goes beyond a contract. I hope this will soon evolve in an interesting discussion, given that a few really clever people have literally picked it up:

A reminder that things we have long treasured, can be new -- and exciting -- to someone else!https://t.co/oRJFFNVjxK

— VisArch (@ruthmalan) May 28, 2016

A calm API uses situational awareness

In “Now Urbanism” Jan 13, 2011 on Informal Urbanism Celine D’Cruz explains:

“It’s important to look at all these aspects … In 20 years what will the structure look like … what do we have to do to make it simple … it’s not so complex to repair”

This post is part 2 of the series "You don't manage the API, the API manages you", which is a story of my experiences with API's over the last years and by no means a guideline for others.

In my first post, I had argued that the the distributed model of stand-alone API gateways is interesting, because it has some semantics from within the system, but no tools on the market fully support it. While there are some standards, like RFC 5988 and JSON-LD, and some implementations like OData, if you like XML/Atom, JSON API (Katharsis) or HAL/ALPS (Spring Data Cloud), they are very limited and with it limit the use of REST itself.

You don't manage the API, the API manages you

We live lives that are waveforms constantly changing with time, now positive, now negative. Only at moments of great serenity is it possible to find the pure, the informationless state of signal zero.

Gravity's Rainbow

Kick-Off for a 5-part series on API's

Inspired by a good, simple, API best practices post from Yahoo, I figured it might help to collect all the stuff I've learned in different companies and projects over the last years on API's - anything non-trivial beyond 12 Factor App, Web API Design and Serverless Architecture. For me, API's are the uniform access point to one or multiple systems. For the sake of this article I exclude API's within the same binary here, so you could argue I speak about stand-alone API's if you want (I don't like the term Web API or Front-End API too much).

Stand-Alone API's, and with it Microservices, are being promoted as "SOA, the good parts". Here, an API as front end to multiple systems is lean approach to SOA with right-sized governance, less canonical data models, and a distributed, scalable, containerised, architecture. Quite simply though, they are just a natural evolution of open ecosystems with ubiquitous, uniform HTTP interfaces, propelled by contemporary service-based business models leveraging duck testing for continuous delivery. A good example of such an API is Firebase for instance, a portal to a PaaS.

Over the course of this week I will share a few ideas I stumbled across in the last years. Some of them might have worked, others not, on some I might have worked directly, on others not. This is not a tutorial, this is a story.