The ABC Guide to Understanding API’s without the Technical Jargons — Part 2
In my previous article, I took the rather free-of-jargons approach to explaining what an API is. I did so in a way that even an 8 year old would understand.
In this article, I’ll be taking a deeper dive into what an API is and how it works and I’ll be using more technical terms. But don’t worry, I’m going to explain it in a way that you have no other option than to understand it.
What is an API?
API stands for Application Programming Interface. So, let’s break this down:
- An application is obviously a software that accomplishes a particular task or job.
- Programming is the process of writing instructions that direct the computer on what to do.
- Interface is more like an intermediary that helps people communicate with something. That’s why you hear terminologies like User Interface(UI) which is rampant in apps ranging from Web apps to Mobile apps. It helps users communicate with a system. For example, WhatsApp’s User Interface helps WhatsApp’s users to communicate with WhatsApp’s system allowing users send messages, upload status, edit profiles, etc.
Now let’s get the general overview of an API.
An API is any software that enables two applications to communicate with each other using defined rules and protocols. These rules and protocols define how these applications communicate using requests and responses(I explained requests and responses later on).
When I talk about protocols and rules that define how two applications communicate, this is what I mean: Say we have 2 applications that want to communicate with each other. Say Application 1 is a Weather Mobile app that I just developed. I just finished building the UI of this app but the one thing the app lacks is the actual weather data that I can display to users of the app to help them stay informed about weather conditions in their area and globally.
Application 2 is the system that has the Weather data that Application 1(the Weather app) needs. Let’s say that it is a database that sits on a server. Now, these two systems are separate and need to somehow communicate so that Application 1 can ask for Weather data from Application 2 and display to users.
THE WEATHER API TO THE RESCUE
As much as these systems are separate and independent of themselves, there’s actually a way for them to communicate. That’s where the Weather API comes in.
Let’s say the company that owns the Database that stores Weather data knew that people like me would build Weather apps that’ll need weather data, so they built an API — The Weather API.
So, they built this API that will enable outside/external applications to be able to connect with their system to get weather related data.
MY API, MY RULES
Remember that I said that the API defines rules and protocols that set the foundation for communication between the applications.
Let’s relate this to the Weather API that the Weather company built. How this API usually works is that before you can gain access to the API and begin to get their Weather data, you’ll need to create an account and get an API key.
This API key is just like an authenticator that grants you access to their Weather data.
So, the API could define certain rules that go along the lines of: “Mr. External Application looking to get Weather related data, please make sure that while sending your request for data, you send the country whose weather information you want to get and it must be in a String format, like 'NG' for Nigeria, 'US' for USA, 'SA' for South Africa.
I SET MORE RULES, YOU FOLLOW
The Weather API could even go further to enforce more rules like: “Also, add the exact date of the Weather information you’re looking for, like(date: '31–08–2023’) ”. It could also say: “If you’re not looking for a particular date but rather Weather data of the past 30 days, add an extra data field that says(days: '30’).
These are some of the rules that the API enforces for external applications that want to communicate with it to get Weather data. These rules are normally contained in something called an API documentation.
The rules make it possible for the Weather API to understand what exactly the external Application is asking for and helps it know exactly what to return to the external Application which brings us to the concepts of requests and responses.
THE CONCEPT OF REQUESTS AND RESPONSES
Remember how I used the waiter analogy to explain the concept of API’s? I talked about how you make a 'request' to the waiter for your favourite dish on the menu and how he gets it from the Kitchen and returns it back to you as a 'response’.
The Application that needs or asks for the data makes a request, which in this our example is our Weather Mobile app. The API takes this requests and tries to make sense of it to see if it follows the rules that it set. If the request follows the rules, it interpretes the request (in our example, it gets the country of the weather data and the date of the exact weather data it needs, just like in our example), then it fetches this data from the weather database and sends the weather data it needs to the weather Mobile app as a 'Response’.
Don’t forget that the data sent back to the external application is the response.
This is the usual dynamics of an API.
CLASSIFICATION OF API’S BASED ON ARCHITECTURE.
There are different ways in which an API can work or rather different architecture or types of API’s.
- SOAP API’s: The API’s use Simple Object Access Protocol. The client(Weather Mobile app in this case) and the server (database system) exchange messages using XML and they were more popular in the past.
- RPC API’s: They are called Remote Procedure Calls API’s. The client completes a function on the server and the server sends back output back to the client.
- Websocket API’s: They use JSON objects(JSON is just a format in which data is structured) to pass data. It supports two-way communication between client apps and server. The server can send back messages to the client apps that are connected to it. This is the kind of API real time messaging applications like WhatsApp use that makes it possible for you to get messages immediately your friend sends them even while you’re still typing.
- REST API’s: This is one of the most popular API’s out there and this will be our major focus from here on out. Here, the client(don’t forget that client refers to the application that needs data) sends a request to the server as data. The server takes the input data that the client sends and performs some functions to get the exact data the client requested for and sends back data to the client as response.
REST API — THE MOST POPULAR API
REST stands for Representational State Transfer. REST defines some set of functions like GET, POST, PUT, DELETE that the client can specify if they want to get information, send information to be saved on the server, update information or delete information on the server respectively.
The main feature of REST is its statelessness, which means that it does not save client data whenever between requests. It uses URL’s which we call endpoints to make requests to the server.
HOW REST API’s WORK
For example, on WhatsApp you can change your username and bio, right? So, how does this go down? How does WhatsApp collect your new username and bio and change it on their server?
WhatsApp could have an endpoint responsible for changing your username and bio like: https://www.api.whatsapp.com/changeUsernameAndBio (since we don’t know the exact endpoint WhatsApp uses). Don’t be confused by the URL. Yes, it looks like a website URL, that’s how endpoints are. They use Http to send requests and responses.
So, after typing in your username and bio and clicking on the submit button, this is what happens: The app takes the username and bio and sends a request in form of a JSON object to the endpoint we stated above.
{
"username" : "Victor The Coder",
"bio" : "The only real limitations we have are the ones we lay in our minds"
}
The above format is a JSON format which is a way in which we usually structure data for REST API’s. So this JSON data is sent to the endpoint: https://www.api.whatsapp.com/changeUsernameAndBio.
When the API receives the JSON data through this endpoint, it takes it to the exact table in the database where usernames and bio are stored and updates your username and bio and sends a response back to WhatsApp app, telling it that it has changed it successfully. The response sent back to WhatsApp could look like this:
{
"success" : true,
"message" : "Username and Bio updated successfully"
}
When the WhatsApp app receives this response above, it can take the “message" data and display it to you informing you that everything went fine.
OUR HERO-API ALWAYS SAVES THE DAY
You see how the API has allowed the client(WhatsApp app) and the server(WhatsApp’s database) communicate successfully? Yes, that’s exactly the function of an API — enabling two independent systems to communicate and send data to each other.
We’re drawing closer to the end of this discussion and I believe that you now have an in-depth understanding of not just what an API is but how it works as well as its types.
You’ll notice that I placed more emphasis on REST API’s because they’re more popular and the most widely used and you’ll be dealing more with them in your programming career than other kinds of API’s.
I hope you enjoyed this read. In the next sequel, I’ll be showing you how to consume API’s and get information from them to display in your mobile app and I’ll leave the Github repo with you.
So, till we meet again, Gracias. Don’t forget to leave some claps and hit the Follow button if you found this article helpful.
Don’t forget to also follow me on:
