Conversations

At the API Strategy and Practice conference, I gave a workshop on API 101 (slides).  I was lucky to have my actual mother in the audience so I could make “Even your mom can understand” jokes, which was great (I got her permission first, and kudos to her for letting us gently tease her in front of 150 strangers).  But also it gave me the opportunity to give a talk that even my (very smart, artistic, non-technical) mother could understand.  As I was working on the more technical pieces I realized that we have a self-referential problem frequently when trying to describe API Transactions.  We talk about parameters, headers, meta-information, requests and responses as if these terms were meaningful to a real person. Not really, no.  So, I submit the following thoughts for your consideration.

So first – what is an API? What is it like?  The easiest comparison I could come up with was the old time switchboard operator.  Your phone didn’t have to know how to get ahold of Aunt Mae, it just needed to know how to talk to the operator, and he or she would do what was necessary to connect you two.  An API is a computer version of this abstraction.

Now, for the juicy bits.  Transactions are conversations between computers.  This conversation can be boiled down to something that should amuse people who know me at all. Follow along while I describe the pieces of the HTTP Transaction like ordering an iced tea from Starbucks.

• Resource ID: “Iced tea”
• HTTP Verbs
  • POST: “I’d like to order an iced tea”
  • GET: “Can you read my order back to me?”
  • PUT: “Actually, make it larger”
  • DELETE: “Oh no, I left my wallet at home! Never mind”
• Parameters: “Extra ice, unsweetened”
• Headers: “For here or to go?”

Once you’ve walked through this conversation example you can get a little more technical – your browser uses headers to tell the server what language you speak.  Changes and substitutions are added to the name of the item.

I challenge my geeky friends to think of other ways to describe technical things without using technical terms that are meaningless to the general public.  What other examples can you think of?