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.

The ephemeral context

Over the holidays, I've read a nice outlook by FJORD and an awesome rant by Maciej. Though the two publications could not be any more different in any sense, they touch on a similar topic:

The re-emergence of context

Back when I was studying mobile application development, it was all about context - changing texts and pictures, structure information, optimize information to location and usage, cram information on a small screen, those things. With responsive, atomic and material design, the focus shifted more and more into grid systems and ordering components efficiently, under the assumption that screens converge so much that all information is equal.

While responsive design works beautifully in many situations, the technical difficulties and trade-offs** superseded the initial idea of contextual design. However, with the "disappearance of apps", context becomes more important than efficient design. With smarter notifications, smart watches, the aggregation of information into other streams and more participatory and collaborative software service usage patterns, giving the right information at the right time becomes the major value proposition. Uber and Airbnb (with new Google Maps ads), Amazon (with Echo), Tinder but really anything that shapes an environment into a service, like IKEA, Google Now (as in Her) or Nest, are on the forefront of this movement. They don't respond to context, they create their own, ephemeral, context.

Reverse CQRS

This means mobility and analytics, in the form of deep learning, merge more and more. Mobility brings its knowledge of context into analytics, turning the flow of applications around. This makes event sourcing the new user interaction, separating the query (as in CQRS) from the command - the event becomes the query, really, and the command, as in the interaction, is executed on an interesting result.

From a service design perspective, this means we need to build stronger mental models, but as concept are harder to reason than to visualize, we need to find a way to explain them better first. We can't just respond to a demand, like opening an app, but must provide different entry points (not just API's) to services, that provide their own feedback loops. Not only, as mentioned above, as entry points via operating system hooks, like notifications. Rather with completely new, independent behaviour, starting from where we see it today for secure logins on a risk basis (e.g. the new Captcha) or proximity-based suggestions. A service design flow looks very different if there is more inputs than outputs. There is a reason SAP looks into interactive programming, and I hope Tesla's ideas for carsharing and using cars for autonomous tasks will soon be reality.

As usual, I believe communication can solve this - call it patterns, guidelines, or I've written about wrong proportion recently, but you need to establish loosely coupled "atomic" interactions, or agents, that can react to "reverse CQRS", like Redux advertises it. The analytics is actually rather straight forward, it could even start with a simple subscription model, but splitting your application flow down will be hard work - especially for all the responsive web apps that used plain old MVC and hard-wired their controllers with the overall flow.

*) Disclaimer: I work for Accenture, which is the parent company of FJORD.
**) I have myself just been on a very service/product-driven software project where we had many of those

9 Books about Architecture

This post is published in December 2015, when I finally found the time to proof read and check. This post is a snapshot of my thinking back at this time.

For a long time, I've had the reading list on the left panel. However, over time it felt a little bit un-curated. Inspired by a list of recent retweets from Jeff Sussna, especially a post by Mike Sall, I thought compiling it differently could make sense.

Let's dive right in - here is my list of 9 (well, actually 12) Architecture Books every interested Software Practitioner should read:

Basic Architecture

These are books that give you an initial understanding of what Architecture is about (hint: something "entirely different") without being to engineering-heavy (if you want that, read Francis D.K. Ching), patronising or historic:

Matthew Frederick, "101 Things I Learned In Architecture School". A small, lovely, extremely simple book that gives you a first glimpse of how to think like an architect.

Doug Patt, "How to Architect". An indexical volume of architectural elements, making it an easy reader and introduction to architecture. Mainly because of his great videos, actually.

Anthony di Mari's "Conditional Design" and "Operative Design". Because it shows the commonalities of structural elements and patterns in building and software architecture in a simple, visual way (as opposed the Alexander's "Pattern Language").

As a bonus: Joel Kotkin, "The City". Not strictly architecture, as it is about urbanism, but a great, short, intense history of human habitat, before you read Jane Jacobs.

Elementary contemporary texts

These are texts that defined contemporary architecture, giving you a feeling of the philosophic foundations of "living and dwelling" - something that is often ignored by engineers talking about architecture.

Robert Venturi, "Complexity And Contradiction In Architecture". Not an easy read, but one of the most defining ones of contemporary architecture. A manifesto against dogma and black and white thinking, introducing the hybrid, notably one of the most often used concepts in IT (often read as counter-example of Le Corbusier's "Towards a New Architecture" and only followed by Bjarke Ingels "Yes is More").

Ram Koolhaas, "Delirious New York". Because it took complexity to the next level, added emergence, and cross-pollination between society and building. Read it as Conway's Law and be astounded. No idea why, after that, it took Architecture so long until Marc Kushner introduced feedback to it.

Kate Nesbitt, "Theorizing a New Agenda for Architecture". An extremely well curated collection of elementary texts that stands out not only as a reader, but for bringing all of those thoughts into a structure that, at least to me personally, was never before so clear.

As a bonus: Fred Brooks' "Design of Design", because it is a software book dealing with architectural design.

Tertiary Literature

Those texts are not directly about architecture, but about the motivations of architecture, it's impact on society and the public.

Adam Sharr, "Heidegger for Architects". Actually the whole "Thinkers for Architects" series is pretty good, and this is just one example. Architects like, and learn, to think from the perspective of other disciplines. Might be a good example for IT.

Stewart Brand, "How buildings learn". Brand is a classic, working on the edge of design thinking/service design since the "Whole Earth Catalog". This is a great introduction into the evolution of buildings and hence an answer to the question: Can architecture emerge?

Geoff Manaugh, "The BLDGBLOG Book". Imho the single best blog about architecture in the interweb, probably the only real alternative to an AA files subscription. The book captures the full spectrum of cutting edge contemporary ideas into one volume.

As a bonus: Jo Steffens', "Unpacking My Library: Architects and Their Books" is a nice tabletop book listing a wide range of architects and their favourite book inspirations - Thomas Pynchon's "Gravity’s Rainbow" is named surprisingly often.