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