Improving API Design With Boundary Objects

Let's not mince words:

Automatically generated interfaces fail for all but the most trivial of API cases.

For the better part of the decade, vendor after data vendor has teased a promised land where all developer roads circumvent the design process. Just drop in a database schema, press a button, and PRESTO: distributed systems magic.

And yet, these approaches rarely produce API with transformative business value. We need to talk about boundary objects to understand why. In the process, I'll show why the conversations to create an API definition to a specification - a boundary object - is so clutch.

BOUNDARY OBJECTS SPAN COMPREHENSION CHASMS

In sociology and technology fields, boundary objects are artifacts that facilitate collaborative communication across different communities. In any sufficiently large software project, for example, there are multitudes involved. Each of these groups will have a different understanding of the problem to solve.

Suppose, for example, we are a health care provider that wants to allow its members to check in and get updates on appointment wait times from their mobile app. To make this happen, multiple groups are involved:

• The people making appointments who are trying to minimize frustration and wasted time
• The medical practitioners who are trying to maximize useful service and minimize stacking schedule disruptions
• The mobile app team thinking in terms of human-centric design and working under design system constraints
• The branding and marketing team who have its own operation guidelines and marketing scheduling commitments
• Legal, whose job is to ensure the new feature follows state and federal laws, like HIPAA
• There's the cyber/security representative, who is driven to minimize risk through any ingress/egress
• The middleware/infrastructure/platform team managing the shared platforms and processes
• Finally, there's the backend team responsible for exposing appointment management as a capability

That's multiple roles that are each working under different constraints. Each group has its expertise, often expressed in its language; a company's legal representative has a different understanding of the words "proxy" or "domain" than the platform team responsible for the API gateway. Bridging these understandings must occur or a critical aspect of the API will be missing at launch - a mistake detectable when the surprising swift 'Version 2' is released.

A boundary object supports collaboration while not forcing complete agreement. The legal team may still assume "domain" relates to ownership, while the platform team thinks of domains in terms of URLs and request routing. Establishing a common ground does not mean all sides must accept a single definition. But a valuable boundary object facilitates understanding between those different worldviews.

API DESCRIPTIONS ARE BOUNDARY OBJECTS

The process of creating an API definition requires several conversations across these teams. This communication seeks to understand the other's person's perspective, building relationships between their knowledge, beliefs, and assumptions and our own.

Rather than seeing them as messy human interactions to be avoided, people embracing boundary objects create understanding greater than the sum of its parts. Codifying that shared understanding into a human-readable (and machine parseable) format - like OpenAPI, RAML, API Blueprint, or even WADL - preserves the hard work of understanding building long after the regular meeting invites have ended.

Further, creating a boundary object, like an API description, means we can continue investing in the grounding process; these artifacts can continue to be contributed to by anyone who can edit text and follow the company's source control process. And this will happen - a key distinguishing factor of a product is that the ongoing repairing and realignment to avoid miscommunication continues even after launch.

CREATING SHARED UNDERSTANDING ISN'T PUSHBUTTON

John Allspaw has done a fair amount of thinking about creating this understanding. While Etsy's Chief Technology Officer (CTO), he delivered the presentation "Common Ground and Coordination in Joint Activity". He correctly points out that the mismatch in common ground is one of the primary ingredients in comedy.

A failure in common ground occurs when:

• Party A believes that Party B possesses some knowledge
• Party B doesn't have this knowledge and doesn't know they are supposed to have it
• Therefore, Party B doesn't request it
• This lack of a request confirms to Party A that Party B has the knowledge

The full paper that John talks about is available online. From the abstract:

"Joint activity depends on interpredictability of the participants' attitudes and actions. Such interpredictability is based on common ground-pertinent knowledge, beliefs, and assumptions that are shared among the involved parties. Joint activity assumes a basic compact, which is an agreement (often tacit) to facilitate coordination and prevent its breakdown.”

How often, when we review an API, is there the requirement for an ID for the request to be accepted but no clue provided for where that ID can be obtained? Or that there is a prerequisite to be successfully performed (information validated, an account created, etc.) before the desired use case can be performed.

Creating a boundary object addresses these omissions and creates that common ground. Auto-generating an API from whatever model is handy, like data, may be quick at first. However, the ongoing support due to miscommunication will drag on the API teams velocity for as long as they are responsible for that API. And that's not very funny.

When company practice inadvertently creates siloed teams, a focus on boundary-spanning practices, like creating boundary objects, will be where value is created. Pick up the phone. Have that meeting. Begin creating that common ground.

MILESTONES

• Chris Richardson re-upped his "anti-patterns of microservice architecture" based on recent conversations. Lots of great advice is in that thread.
• 42Crunch released a new ebook, "API Security: A Blueprint for Success".
• Daniel Bryant (Ambassadorlabs, InfoQ) is thinking about the 8 Fallacies of Testing Microservices. If you have some thoughts, slide into his DMs. Or comment on his tweets directly.
• I missed this in last week's newsletter, but GitHub has deprecated one of their GraphQL APIs in favor of a REST one. Github has been one of the most prominent "public" GraphQL API examples. This might be an isolated incident or, as suggested by Mark O'Neill, the beginning of a slide into the "trough of disillusionment". Something to watch.

WRAPPING UP

Again, as a reminder, Patrons aren't being charged for September. However, if you're interested in helping ensure these emails remain free of ads, paywalls, or information sharing, head to my Patron page and sign up.

Till next time,

Matthew @libel_vox and matthewreinbold.com

While I work at Concentrix Catalyst, a basket of kittens and knowledgeable as they are cute, the opinions presented above are mine.