By Jason Harmon | Feb 28, 2013
I’ve found myself explaining to lots of people what it is that I do, in working with APIs. Sure, at the office or a conference, I feel understood. However in social settings or around family, I sometimes feel like people just think I’m making this stuff up. When I try to use acronym and industry jargon filled phrases, I often just get glazed over stares and slow head nodding.
“I offer a series of integration points for mobile, web, and B2B web services consumers. Our RESTful API provides partners and developers and opportunity to monetize their application development by utilizing our marketplace platform.”
…"{crickets chirping}"…
I’ve tried to come up with some metaphors and analogies which help describe, to the uninitiated, what exactly an API builder does. In some situations, I think some of them have fallen flat on their faces, and others have switched on lightbulbs. Your mileage may vary, take it for what it’s worth.
-
“All of your mobile apps are powered by APIs”. This one gets a positive reaction (everyone wants to understand how those snazzy mobile apps work), albeit a still somewhat ambiguous vibe. I don’t think that most folks know the difference between a SQL database connection, a NoSQL database connection, and a RESTful API call. They just know data comes from somewhere to paint a screen on their phone.
-
“You can’t build a car/plane/whatever without good components”. This starts out rough, but gets easier, at least in describing hacked compilations of various APIs. I try to explain that a car or plane company doesn’t make gauges, shocks, and sensors; they rely on specialists to provide those components. In terms of apps/sites which can do lots of different things, they rely on API providers to create great components in their various fields of specialty.
-
“Brain of the business”. I think this comes off as arrogant sometimes, but it’s my attempt to explain the value of APIs. The notion that an API attempts to consolidate business logic behind some facade is where this comes from. This idea that we have some abstracted rug under which all business logic is swept. This has worked best for talking about more enterprise type scenarios.
-
“We are librarians managing the card catalog”. Far and away my most abused metaphor, probably due to my obsession with wanting a really cool old handcrafted card catalog in my home office. I think I’ve used this primarily in terms of describing the sorts of personalities we look for in talent acquisition for API builders. Unfortunately for younger people out there, I’m afraid they’ve probably never used a card catalog in a library, but I tend to hope they at least get comparison. There is a discipline in what we do which requires a deliberation of minutia not often seen in software, much like the discipline of running a library full of books. Knowing that we have to accurately describe the functionality of some abstracted business concept, and describe it’s interaction patterns in painstaking detail. Anyone can walk into the library and lookup their book by various parameters in a consistent manner by using the card catalog, much like we expect that our API consumers can find the data they need in the same way.
I’d love to hear how you describe how APIs work to family/friends/business associates. Our field is one of disciplined craftsmen, quite often also some of the more intimately creative people I’ve had the pleasure of meeting. Hopefully some of you are more eloquent at describing this than I am, and can help provide me with better ways of evangelizing the virtues of our practice.