An API Analogy

When I first learned about APIs they didn’t really make sense to me. Probably because APIs are flexible and can take many shapes. Let’s take a trip to the store to better understand web-based APIs. An imaginary trip.

If I want to buy some shoes I can look up an address and as long as I go to that address I have access to lots of types of shoes. I can choose all of them, none of them, or some of them. I can also do what I want with the shoes I select. Wear tennis shoes to a swimming pool? Let’s go! Take some rubber shoes and tear them apart to make a belt? I don’t see why not.

This is a lot like a web-based API. As long as you go to the right address (endpoint) you can have the JSON payload that lives there. What a gift! You can then take all or none of it and use it in your application.

Let’s say you are making an application that needs to be able to define a word for a user. Do you want to store all of the words in the dictionary in your database? Most likely the answer is no. So you could make a call to something like this dictionary API & gather a definition as needed. Someone out there in the world created a JSON response that you will receive back. The response looks like this:

This is the contract. If you hit the endpoint you will receive this JSON response back. No more. No less. Well… there is a little more since I didn’t want to paste a huge photo here.

If you look through the response what do you see? Is there a word? The pronunciation? The meaning(s)? Also, notice what isn’t in there. Do we see how many times this word is used on Twitter?

You can take this information and do whatever you want with it in your application. You may use all pieces of this response or only some. Just like you may buy all of the shoes or none. It is all available to you, as long as you know how to parse it in your favorite programming language.