Wednesday, 1 June 2016

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:

Emergence becomes a big topic in urbanism as well, as with emergence, patterns of forces become more interesting again. I had written before about Tatami mats and the Japanese structure of the city, how cities grow much more like Microservices nowadays - an observation that Mark Burgess is investigating in now. But for services, doesn’t mean you can’t design by contract. Just because you can’t create a grid on city doesn’t mean you can’t control it. Legibility and Indexicality just become more important than order. How a consumer reads an API becomes more important than how you specify it.

I've used Story Mapping in the past and am, thanks Henrik for the suggestion, looking forward to read "Mapping Experiences", a book that will also include user journeys and ecosystem mapping. In Story Mapping, also the grid, the system of stories is key. I am looking forward to service documentation that includes SLA, Quality, Roadmap etc, maybe in OpenAPI, and that covers topics such as immutability instead of state transfer and message passing. I've made good experiences with Swagger in Camel (again OSGi), and I believe approaches such as Spring REST Docs are interesting - I just don't like that Pivotal seems to build it's platform mainly for Netflix and continuously ignores standards such as JAX-RS 2.0.

How do keep documentation resilient I still struggle with, with the right proportions for architecture visualisation - Simon Brown does that better anyways, and he has the nicer city travel analogies. But maybe a little more collaborative - like the 500 lines project? Or by using more interesting patterns like the way Redux thinks about data flows, as streams with an intent towards an information change, like a reverse CQRS, and see how we could show flows more like they really happen instead of weird concepts such as "routes" in EIP that seem to be more aimed at restricting flows.

Just like Rem Koolhaas once said in a talk about the Metabolists who were the first to see the 
"city as stream of events instead of agglomeration of form"

No comments: