Thread by @conways_law

APIs EXCLUSIONARY AND INCLUSIONARY
A Twitter Essay

When I moved to Massachusetts in 1961 the common street-sign practice at intersections was to name the side street but not the main street. It’s still general practice.
1/20

The underlying design assumption was obvious to newcomers like me:

IF YOU DON'T KNOW THE NAME OF THE STREET YOU'RE DRIVING ON YOU DON'T BELONG HERE.

The lesson:
Certain design choices are inherently exclusionary, and are almost always invisible to the designers.
2/20

The way we partition applications today is largely based on the UNIX Philosophy.
en.wikipedia.org/wiki/Unix_phil… .

The UNIX Philosophy is brilliant and has served us exceedingly well. There are several statements of it in the Wikipedia article.
3/20

I’m going to pursue one design principle, cited twice there:

“Write programs to handle text streams, because that is a universal interface.”

This is an important and productive principle, but it’s very 1970s, based deeply in Procedure/Data thinking.
4/20

Object thinking, which emerged at about the same time, has replaced Procedure/Data thinking in programming languages, but barely in API design. When Web protocols became central to distributed applications, Procedure/Data thinking was locked into API design.
5/20

This Procedure/Data lock-in embodies the same exclusionary design assumption as New England street signs. Why?

You have to be an insider to build something with Procedure/Data APIs.

You have to understand the details of the programmatic interface.
6/20

What would a more inclusionary alternative look like? I’ll answer in three steps:
A. I’ll describe an example that we all understand of a general principle.
B. I’ll state the general principle.
C. I’ll apply the principle to API design.
7/20

A. The example.
Before John von Neumann invented the digital-computer instruction set (that is, computer control as data stored in the computer's memory), to program an application you had to understand digital logic and use that understanding to rewire the computer.
8/20

(Search Google Images on “ENIAC programming” and notice the almost complete absence of men.)
phillyvoice.com/70-years-ago-s…
9/20

Computer control as data is software.

Von Neumann’s invention created the software industry.

Computer control as data opened up the field of computer programming to people who didn’t understand computer internals. They just had to learn a programming language.
10/20

B. The principle.
Think interfaces. Not interfaces between artifacts (i.e., creations) but between communities. In the example the two communities were engineers, whose jargon (practice language) was digital logic, and mathematicians, whose jargon was solution algorithms.
11/20

The instruction set is an interface that unites two communities whose members don’t have to understand each other’s jargon. It empowers the mathematicians to build useful new artifacts based on math jargon without understanding digital logic jargon.
12/20

Let’s call an interface between two communities of practice with distinct jargons, that empowers members of one community to build artifacts based on the artifacts of the other community, a “cross-jargon interface” (CJI).

The digital computer instruction set is a CJI.
13/20

C. Application.
How to turn APIs into CJIs? It might help to envision two distinct communities of practice, and how a CJI would open up new artifact construction to one of these communities. I’ve done that in one case; I invite you to think of others.
14/20

I wanted to partition interactive applications into two parts: a back end where the domain logic is specified, and a front end where the user interaction is specified.

AND I wanted to make the front end code-free so that non-programmers could build interaction behaviors.
15/20

I had previously developed a set of design principles for a maximally-inclusionary way to build such things:
melconway.com/Home/pdf/human…

I have called the interaction part “wiring diagrams”. You can see the partition design here:
melconway.com/talks/2019_con….
16/20

The purpose of this exercise has been to open the application-software-building market (the new artifacts, in CJI-speak) to non-programmers (the new community, in CJI-speak). The non-programmer “wirers” build their applications by wiring up wiring diagrams.
17/20

Some of the wired components (the yellow ones in
melconway.com/talks/2019_con…)
connect to the APIs of the business objects at the components’ inputs.

The business-object behavior specified by these APIs turns the wiring diagrams into business applications.
18/20

How are the APIs used by non-programmers? The principle is an old one: dialogs as a user interface that hides a formal text language. That’s how the Mac and Windows hide the command line.

The design principle: "Choice over Construction"
19/20

In
melconway.com/talks/2019_con…
you read that the yellow components' input objects manage the API dialogs. The yellow components themselves are fixed and almost empty of behavior.

Voila: an inclusionary API based on Object thinking, not Data/Procedure thinking.
20/20