Introduction to APIs
A breezy introduction to help you understand the basics
Nearly every computer science student who has been around for a while has heard this fancy term: API. Let’s admit it: we’ve all googled it to try and get an idea of what it is but have mostly returned scratching our heads, bewildered (and somewhat discouraged) by the wordy and vague definitions.
I’m here to take care of that for you. I won’t be subverting or bypassing this barrier of the clunky definition; it’s important to understand what those vague terms mean. Rather, I will take this very definition and break it down for you, from one layman to another. 😉
As Wikipedia puts it:
An application programming interface or an API is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.
Let’s think of a restaurant for a second (because why not? 😋)
When you go to a restaurant, you are escorted to a table where you are presented with a menu by the waiter or waitress. You may ask them for the specials, methods of food preparation, waiting times, etc. Finally, you decide on a dish and give the order to the waiter. Then the waiter takes this detailed order to the kitchen for it to be processed, prepared, cooked and delivered back to you by the waiter.🍜🍕😋
Note the incredible effectiveness of the waiter in this situation! Can you imagine going into the kitchen to try and explain what you want on your own? Or have the chef come out mid-cook to take your order?! It’d be madness! In this situation, the waiter acts as an interface or intermediary between you and the kitchen. 😮
An API is the waiter of the computing world. Now you will have some idea of the first part of the definition. An API, as the name suggests, is an interface between two or more software entities which need to communicate with each other efficiently (not unlike you and the chef!👨🍳). Now, this communication, if not handled properly by adhering to some set protocols, can get messy and inefficient very quickly (as we noted in the no-waiters-scenario)!
The role of an API is to facilitate this very communication. But what exactly do we mean by communication? 🤔 Communication here may include requesting some data from or publishing some data to, say, the server of an online service. In addition to this, APIs also perform the task of abstraction of complexity. A developer working on an app that requires weather data does not have to create anything; they just have to just pull the data from a weather API in the desired format without having to worry about how the data was obtained.
APIs are everywhere from smart refrigerators to your own local machine which may need an API to talk to the peripherals, and so on. However, we’re going to focus on the most popular form that it takes today: a web API. A robust and understandable example of this can be highlighted using the Spotify API.
Let’s say you want to build a data repository of the top 15 artists of 2020 by accessing data on which of their songs topped the charts, which ones got the most hits, which ones were shared the most, their fan following numbers and so on. Using the Spotify API, we can request and then import data from their server and arrange it neatly into JSON files (a simplified file format for storing data in human-readable form), which we can then access, explore and operate on however we wish to.
The next natural question is: how do we request this data? Or if we wish to publish or edit data on their servers, how does one do that? Here we come to the second part of this clunky definition. (I hope you keep going back to it and keep trying to connect some of the dots on your own!)
We need a set of conventions and protocols that are followed universally when creating APIs, such that data from any API in the world can be accessed with similar if not the same commands.
And here comes the other buzzword you may have heard of: REST.
REST is nothing but a set architecture or a set of guiding principles by which an API is designed, and consequently by which calls to this API are made. Any API made adhering to the principles and constraints set by the REST convention is called a RESTful API. These constraints are quite lengthy and beyond the scope of this introduction.
However, we can get hands-on trying to make some API requests ourselves, analyze the responses and fix the error messages (but in just a minute)! One of the main principles of the REST architecture is that any data on the server (called a resource) should be accessible through a URI (Uniform Resource Identifier) which is really just another name for URL.
Each URL is called a request and the data sent back is called the response. Before we start making requests, let’s get some things set up and understood.
Any request contains 4 primary parts:
- the Endpoint
- the Header
- the Method
- the Body
Endpoint or root-endpoint is the starting point of the API which you are accessing. For example, the root-endpoint of the Spotify API is https://api.spotify.com/. We can then attach paths to the end of this endpoint to request specific resources on their servers.
Headers are used to give some additional information to the server when making requests which may come in handy for it while sorting and sending a response. One of the simplest examples is:
curl -H “Content-Type: application/json” https://api.spotify.comHere, the -H indicates that the given property-value pair/pairs (separated by a colon) are to be headers. This particular header is telling the API to expect requests in JSON format.
Methods (also referred to as HTTP verbs in various API documentation) are the basic type of request that you want to send. You can see below a list of methods that we can append to the start of an API request:
An example of this could be as given below. -X here indicates that a method is going to be specified next.
curl -X GET https://api.github.com/user/reposBody is used when we are sending some data to the server as part of our request. This can be used for PUT, POST or DELETE requests which all require a data parameter to be passed alongside. An example of a simple POST request with the body would be: (the \ just means we are going to a new line)
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/orgs/ORG/repos \
-d '{"name":"name"}'Here, we are creating a repository (using -X followed by the HTTP verb POST) in the organization ORG and in the header, we have specified the version of the Github API (v3) as well as the format of body input and that of the expected response (ie in JSON format).
Then, we have used -d to indicate that the body (also called data part, hence the d) will be specified next. And as we had specified earlier, the repo name has been given in a property-value pair i.e. in JSON format.
cURL
You may have noticed the keyword curl at the beginning of each request that we have specified above.
cURL (client URL) is just a command-line tool that we use to make API requests conveniently. Curl is not the only such tool but it is easily understandable and most API documentation are written in terms of cURL.
Let’s get hands-on!
Enough talking, let’s start making some requests now! We’ll start with a very basic API request with just an endpoint and a header. We are sending this request to https://icanhazdadjoke.com. As the response, we’re going to get a pretty hilarious (or maybe not 😅) dad joke. Head on over to your terminal and type this in:
curl -H “Accept: text/plain” -X GET https://icanhazdadjoke.comWe have provided a header telling the API that we expect a plain text response and have given a GET method.
Fun Side Exercise: Try and figure out the difference b/w a Content-Type and an Accept Header!
Congratulations on your very first API call! 🥳
Now, let’s make a much more complex request through the Spotify API. When dealing with larger, more established APIs we will require something called an access token. It is part of an authentication or authorization process to ensure that requests to the API are legitimate and authorized. Spotify’s developer website allows us to play with their API in the browser itself without having to write any cURL calls or requests ourselves. We can also get an access token to do so very easily.
Head over to the link below in their interactive Web API:
We are going to try and get some song recommendations from the Spotify API based on a song and artist ID (or a seed entity as their documentation calls it).
As you’ll be able to see, Spotify has automatically provided an artist and song seed for us. Without messing with any of the other fields, scroll down to the bottom and click on Get OAuth Token. You don’t need to check any of the boxes that come up; just click on Request Token. You may be asked to sign in to your account. Do that, and when you’re redirected back, click on Try It.
You’ll be able to see a JSON response containing 10 songs recommended on the basis of the entered song and artist IDs. This is just a small example of the power of APIs and how effective they can be for developers wanting to integrate different software.
Wrapping It Up
There are a smorgasbord of possibilities in terms of what you can do with APIs, but I hope this gave you a good head-start.
Now, that you have an idea of what APIs are and have even made a couple of requests yourself, why not explore Postman? Postman is a desktop-app that has made the process of API testing and request calling much more convenient and universal. If you’re uncertain about where to go from here, maybe begin by learning about Postman!
Here’s a video which goes more into depth on all the concepts I have talked of as well as including a detailed tutorial on Postman. Check it out!
I hope you had fun on this journey with me and that you learned something new. Have a great day! 😄
Also, I would love to connect with you through LinkedIn! Hit me up!
