Skip to main content

Dawn Ahukanna - APIs: Semi-permeable, osmotic interfaces

Deliberate Complexity Conferences 2022 Recap

This talk was presented at Deliberate Complexity Conferences - Building Successful Platforms and APIs on 29 June. We are honoured to present the video recording and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Dawn Ahukanna

Design Principal and Front-End Architect at IBM

Dawn's presentation (video recording)


Dawn's slides



  • Do you see this being generic or front-end only?
  • What inspired this approach?
  • Tell us more about assigning temporal probability parameters to assumptions, that would be presumptions.
  • Can we assign probability distributions to values in complex systems?

"APIs can be modelled using the metaphor of semipermeable interaction boundaries between the intended High-Fidelity human-centered interfaces and the interpretation into a coded implementation. Moving beyond "red-lining" static images, the presentation discusses approaches and recommendations to consider the human developers and operators experiences with APIs, with user interfaces."


Model vs reality

  • APIs are usually specified individually, without suggested sequencing and dependencies
  • Even as a developer, one has to have a model for the sequences and dependencies. There are many known interactions. (The unknowns are the exceptions. And humans.)
  • In software design we usually flatten finite N-dimensional outcomes/problems into 2D infinite planes to describe them
  • Should temporarily presume, record and monitor assigned probability values, especially for foundational assumptions! (as opposed to unvalidated but true/false assumptions)

eg. a web interface: 1D pathway of user interactions, but then errors and exceptions, conditionals, calls to other systems to support this one...

We need a model that allows us to address this multidimensionality.


Introducing Interface Membrane Layers

Fundamentals of the model-metaphor:

  • a semi-permeable membrane only allows certain objects to traverse
  • we compare APIs to behave as semi-permeable osmotic membranes

The experienced reality (a cube space, arbitrarily chosen for this presentation) which we want to model, can be described by its enclosing planes (the 6 sides of the cube). The 3D "reality" space can be thus modeled as enclosed by a 2D set of planes, where each plane is a number of different semi-permeable membranes (APIs) allowing only certain objects to pass through. Describing one space from 6 different orientations -- explicitly.

A modification on Brad Frost's Atomic Design System

  • spatial particles/objects with interactions, layers, membranes in between
  • composition of elements in defined Carbon guidelines, components UX and workflow patterns
  • atoms would be for example the buttons and dropdowns on a web page
  • molecules would be for example a header avatar
  • molecules combine into compounds, and compounds combine into organisms
  • organisms go into placement and flow:
  • organisms are filtered through templates to be placed on pages

Enables a visual (as opposed to text only) representation to show which API is used where, for what, when, how and what's the outcome.


A specific example, for the sequential membranes on one side of the cube

From machine readable database through to the user-facing screen:

  • Each membrane layer filters out non-supported input and that gets handled at that point (rather than percolating it all the way through).
  • The specific and validated combinations create composable views (display views + functional logic/service + styling).
  • These composites go through the last membrane: templates.
  • Pass if they match the requirements of the template and if they have a place.
  • Lastly the page layer (= screen) aggregates, calculates and generates in real-time all previous layers and displays the final result.

Sign up to the Deliberate Complexity Newsletter so that you never miss out on the latest recaps and the API Resilience podcasts.

Sign up


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.