If you had told me two weeks ago that in one week's time I would be proudly presenting a project that centered around the use of an API, I would have been dubious to say the least.
Less than two weeks ago was the first time I had encountered the term API.
As my project partner and I worked on our program, we accessed the Ticketmaster API through something called a “key”, which essentially unlocked data for us to use. We created a program which allows a user to search events on Ticketmaster. The user can refine this data by various options including city, performer, and date. You can view a video demo of our project on YouTube here and see our code on GitHub here.
I fully understood all of the steps we were taking as we developed this product, but somehow I could not detect which part of this process could be labeled as the actual API.
Image and quote from "The Princess Bride" (1987)
The purpose of this blog post is to challenge myself to simply and effectively describe what an API is in order to cement my understanding of the subject. In this post, my use of the term API is referring specifically to a web API. Hopefully this post will be useful to developers who are looking for an explanation of web APIs from the perspective of someone who is new to the subject.
Before I define what an API is, I would like to identify what an API is not.
An API is not the data you are seeking. In the case of my project, the information we extracted from Ticketmaster for various events (e.g. artist, venue, date, time, etc.) did not constitute an API. Those data points are part of the expanse of information that makes up the Ticketmaster database we were accessing, and not the Ticketmaster API. This was a misconception that I harbored during this project, so I want to clear that up before diving in.
So… What exactly is a web API?
An API is a bit of code that allows two programs to interact. It is essentially an “access point”. The best way I am able to understand this concept is through an analogy in association with my personal real-world experiences.
It is no surprise that my favorite analogy for APIs involves food—specifically sandwiches. The ordering process at the sandwich shop Which Wich? provides a tangible representation of API use.
At Which Wich? to make an order, you fill out one of the available sandwich forms at the front of the restaurant and submit this form to the cashier. The sandwich forms involve various check boxes for the type of bread, meat, toppings, etc. and are printed on brown paper bags that are eventually used to hold the sandwich. Once your form is submitted, the kitchen then crafts your sandwich according to the specifications you requested and puts the finished sandwich into your paper bag sandwich form. At this point, your name is called and you may collect your masterpiece from the cashier.
If you are not familiar with ordering at Which Wich?, this YouTube video has a brief overview of the process:
Video by Marina Amdream, 2014
In this analogy, the business’s sandwich forms are playing the role of the API, and the sandwich supplies are the data that you wish to access. You (as the customer) are playing the role of your program. Just like the sandwich forms, an API has a set of rules you must abide by in order to access the desired information. If you follow the rules, you are likely to get what you ask for.
So this should mean that if a customer asks for a turkey sandwich on rye with avocado, tomato, pickles, and lettuce, then that is what she should get...right?
Not necessarily. What if the shop happens to be out of tomato today? It is not uncommon for APIs to have incomplete or missing data. This is something that my partner and I learned as we interacted with the TicketMaster API. At this point, it is your decision as a developer how to handle missing information. In our case, we elected to essentially label the sandwich with a note that said “No tomatoes available today”.
In a similar scenario, you could imagine a customer asking for something that is not only 'out of stock', but is simply not an available option. This can happen with APIs as well.
For example, if the Which Wich? customer adds in an additional box selection asking for chocolate sprinkles, the kitchen is not going to process this request because the option for chocolate sprinkles does not exist. By requesting an unavailable option, the customer risks not receiving a sandwich at all. As a rule of thumb, both in APIs and at Which Wich?, examine the available options and do not request things that are unlisted. Otherwise, it will be a recipe for disappointment.
If you watched the above video or have been to a Which Wich? before, you may have noticed that avocado is an additional charge. This is similar to an API.
Some APIs only allow public access to certain features and additional features are available for purchase. The API we used for Ticketmaster allowed us access to most of the information we set out to include. One thing that was not included was ticket prices; access to this information could be purchased from Ticketmaster. As an alternative, you could simply visit the TicketMaster site (the url for Ticketmaster was available in the free database we were accessing). For our project, we elected to redirect our users to the Ticketmaster site. In sandwich terms, we elected to skip the avocado "feature" to save a few bucks.
You might be asking yourself why the customer does not just access the sandwich materials directly?
If you try to access the sandwich supplies directly, you will likely get kicked out of the restaurant and possibly face legal action. When a customer enters Which Wich?, she agrees to follow their rules in order to obtain their product. Imagine how difficult it would be to make your own bread, grow your own vegetables, and raise livestock every time you wanted a sandwich. As customers, we agree to follow the rules to access the desired product because the amount of time and effort required to produce the same results on our own would be monumental. It is the same for APIs. We follow the rules because we do not have the ability to develop a similar resource on our own (not without a tremendous amount of time and effort).
In conclusion...
An API is a bit of code that allows one program to communicate with another program to expose something that is useful. One does not “access an API”, but rather, one “accesses a ______ through an API”. This blank space can be any number of useful things: a database, a product, part of a webpage, etc. In my personal example, my partner and I used the Ticketmaster API to access event information from Ticketmaster's database.
I hope that this post helped to distinguish what an API is, and did not make you too hungry in the process.
Top comments (4)
Great example... I keep thinking 'what is an API?' whenever I think about it..
I tend to think of them as function calls but that's not entirely true and I always find the syntax... let's call it.. interesting
But then I rarely use them for fun... and only periodically run into them in my testing
Great explanation !
The best explanation of API I have ever read so far. Thank you.
This is a very good explanation of what an API is and (just as importantly) what it is not.