My job over the past few months has shifted to heavily deal with APIs. That includes integrating Quickbooks, Amazon, eBay etc. as well as making our own from scratch.
Fast forward to dinner with my mother. She’s her usual curious, non technical self, and wanting to know more detail about what I do. Well for me to explain how I made my own Quickbooks Online SDK, I had to cover a lot of ground first.
Me: “Have you ever heard me talk about an API before? Or rather, do you know what one is?
Mom: “Nope”.
My mother works in Real Estate Title, so I use that as my relation point.
Me: “You use software at work right? To manage all the titles?”
Me: “With that software, you can do things like add a new person, add a new title, edit a title, add a document.
So that’s our foundation. She totally understands how her software she uses every day at work can do those things. So I motion to say that those 4 things make up her software’s API. Those 4 things are the functions that her software can do.
At this point, we've established that an API is a group of things that software can do. Great. Now I introduce the idea that I (me) will want to come and build something that would say add 500 titles.
Mom: “That would take forever”
Exactly. That’s why I'm going to build something that does it for you. See I can write code that will add all 500 at once. Pretty great. But in order for me to even do that, I have to know about the software’s API. The makers of the software have told me (maybe on their website) that I can use 3 out the 4 before mentioned things. I can create titles, edit them and even add a document, but they tell me I can't add a new person. The 3 things that I can do, is called exposing the API. Those 3 things together make up the API that is exposed to me to use.
So to recap, I used a simple loop idea, and a large number to help the understanding. I then stick to my 4 functions to explain what it means for software to have functions that aren't necessarily part of the API. Quickbooks can link a bill to a PO, but is that in the API? Nope. (as of 2013)
Now I get to start telling her about what I was excited about in the first place.
So if I wanted to write that program that adds 500 titles, I would need to talk to your software. The API has a brain (API backend) and a language (XML, JSON). The brain is complex. It needs to know who you are (authentication) and it needs to know a lot of details in a very specific way. In fact the way it understands things is with language. Just like humans, when I speak English you can understand it.
But what if I spoke English but you thought in French? Then it would be pretty hard to understand me.
The way software makers solve this problem is by having a translator. The translator (SDK) speaks your language (PHP, JS, Ruby, Python). So you can talk to the translator in English, and he already knows how to talk to the software in French.
Mom: “Why does the software speak french?”
Me: “Because the makers do, and that’s what they understand”
There is a problem though. The problem is that SDKs for a lot of softwares are pretty bloated, or non existent. If your software doesn't have a translator for your language, you're kind of SOL. And a lot of the SDKs for say Amazon, Quickbooks or eBay are archaic, bloated or otherwise just terrible.
So what I did to solve the above dilemma, was learn French.
I make what’s called Literal SDKs. Basically, instead of using the SDK that is my language of English, I learn French, and make my own translator into English. One that is quick, clean and to the point.
But the key that makes them literal, is that (back to the mom example) even though the brain is complex in the way it understands, it does a nice job of telling you the 3 things you can do. So it was kind of obvious this whole time, if it tells you “you can do these 3 things” let’s just do those 3 things. That’s what the Literal SDKs do.They aren't complicated, they abstract away everything else and let you do those 3 things.
So, I’ve had this conversation with a lot of friends and family. And so far they all pretty much understand how API’s work, what an SDK is, and why APIs take time to get working in the first place.
Use an example of software they use
Pick 4 basic things that software can do that they understand
Talk about making a loop to solve some massive problem that they hate.
Explain that the software let’s you as programmer do 3 of the 4 things
Talk about how it takes language to talk to an API, and often the language is one that needs translation.
Then finish it off with something whimsical like, now do you get what I do everyday?
P.S. If you make an API for some web app, don’t make them where you need SDKs. They don’t have to be that complex. Tell users what your methods are, tell them how to sign a request, and let them make the damn request themselves. Looking at you Facebook and your PHP SDK.