Drawing APIs: evolving our visual vocabulary

About a year ago, I posted over at the Sunlight Foundation’s blog about a facilitation tool with which I had been experimenting:

I find that it’s harder than it should be to have focused and effective conversations with non-technical people about open data, in large part because one of the key concepts involved is often described by an acronym (API), which itself abbreviates a phrase (‘application programming interface’) that is utterly ambiguous. This is the kind of problem that might only get worse when more words are thrown at it. …

So, I conducted an experiment at TransparencyCamp, and it turned out pretty well! The experiment was called “Draw An API,” and the instructions were:

  • Someone describes what an API is.
  • People draw what they think they’re hearing.
  • Everyone discusses the results.

The results of this experiment were great! We had a range of excellent metaphors emerge from the debut “Draw an API” session, generally along two themes: APIs as magic, and APIs as robots.


As I described in the original post, this pair of broad categories (robots and magic) is telling — and, I think, troubling. 

At a conference like Transparency Camp, even the non-technical attendees are relatively tech-savvy — and yet even among that influential group, this essential technical concept is still indistinguishable from magic. I believe it’s really important that we find ways to demystify such technology, to drag it out of the realm of magic and into a context in which non-programmers can at least participate in dialogue about it. There’s simply too much at stake in such conversations to cede them entirely to technical people. (For example, consider this thoughtful post about the relevance of API accessibility for labor rights; that kind of power analysis could be done in pretty much any domain of civic interest.)

Anyway. The winner of the contest (a robot bartender) got noticed and retweeted by Tim O’Reilly, and some people put out a call for a digital version. Ainsley Wagoner came through this iteration:

Robot Bartender API - Ainsley Wagoner

The robot metaphor seemed to be, on balance, the favored way to convey this technology. So we toyed with it in the DC Open211 project.  Lead organizer Jenn Stowe developed a visual vocabulary that started with individual bits of data and iteratively worked up to the more complex concept of an API-as-robot:

And we soon produced another iteration (with Matteo Becchi, during the Rebuilding Re-entry hackathon) this time of a complex, ecosystemic narrative:

DC Open211 drawing by Matteo Becchi (@MatteoRocks)


And I’m now comfortable enough with the iconography to be able to quickly assemble crude visual aids that convey particular configurations of technology, data, and institutions:

My shorthand visual description of our current phase of the DC Open211 pilot project.

My shorthand visual description of a hypothetical configuration of the DC Open211 pilot project.

My hope is that we can get to a point where we can effectively convey complex technical concepts, right alongside matters of ownership and institutional responsibility, to non-technical people at a glance. We have a ways to go. So far I’ve gotten very mixed reviews about this particular robot (for some reason, Canadians seem to hate that little guy) possibly associated with one’s level of affinity for ET and/or Johnny Five. (My affinity for each is high.) The next step may be to refine these icons and create our own set at the Noun Project.

Thanks to all of those who have helped this little project inch along so far — and be in touch if you want to give it a go at the next iteration 😉

23. June 2015 by greg.bloom@gmail.com
Categories: Community Resource Data | 1 comment

One Comment

  1. Pingback: The Open Referral API project – Open Referral

Leave a Reply

Required fields are marked *