The Beginner’s Guide to Understanding APIs
The first time I heard about the concept of Application Programming Interfaces (better known as APIs) I was only in my second year of study. Honestly speaking, I can’t say I actually knew or had any idea of what they were. I figured it must be some convoluted multi-platform magical piece of software/tech or something.
At that stage, only a few of my peers could explain properly what an API was, because quite frankly they too only had a theoretical and very abstract understanding of it. All they could say was you use it to regulate communication between your database and application, typical textbook regurgitation at it’s best.
I was left with no choice but to scour the internet in search of understanding, and, slowly but surely, as I read article after article, and doing a few tutorials, my understanding of them grew to what it is today.
Now, as a full stack developer with over 2 years of experience, I can say I am quite confident with my understanding of what APIs are, and after reading this, so can you.
The technical definition of an API is “ a set of subroutine definitions, communication protocols, and tools for building software”. It’s a bit of a mouthful, I know, and quite frankly most of us don’t really know what that means in plain English.
To simplify this, APIs can further be defined as “a set of clearly defined methods of communication between various components”. With emphasis on the communication aspect. Try to keep this in mind as you read on.
Sure enough this may shed a bit more light on the concept of APIs, but if there’s anything I’ve learned throughout my days as a student is that memorizing technical definitions doesn’t always mean you understand ‘What this thing is’.
Before I give my own definition of what and API is, I’d like to define a couple of terms:
- An API Consumer is anything that uses (consumes) the API and it’s resources.
- An API Request is a call to an API.
- An API Response is the result received from an API call.
Now, in simple terms: an API is a hosted resource that receives requests, processes them and returns a result in the form of a response.
Emphasis is placed on “hosted” because it can accessed over the internet and “resource” because it can be used to enhance your application.
A simplistic definition and from the perspective of an API consumer it functions much like any other method, only catch is, it’s completely independent of your application.
You simply make a request to the API, passing it what ever relevant data is needed, and it sends back a response. This can be anything from a simple data fetch request to an instantiation of some calculation which will return a response.

At this point I hope I’ve shed a bit more light on your understanding of the whole concept, but as I mentioned above, we need more than just definitions alone. So, lets try applying this new found knowledge to an example.
Example
https://api.github.com/users/seal12
Above is a simple GET API request. If you follow the link above it will show you a page with some of my GitHub data, as can be seen below.

How it works is quite straight forward. When you follow the above link, your browser sends a GET Request to the GitHub API, it receives the request, processes it and returns a JSON object containing my data.
Great!
Before I go on, it is important to note the relationship between an API and an API endpoint:
- An API Endpoint is one end of a communication channel, more specifically the end where the resource is can be accessed, basically it is a url that gives you access to a specific resource (e.g. a specific user’s data like GitHub url above).
- An API is essentially a collection of these endpoints. The API is thus an arsenal of API Endpoints, hosted by GitHub in this case.
The API endpoint in this case can be defined as:
https://api.github.com/users/:username
Where :username can be replaced with anyone’s GitHub username. If you have a GitHub account you can try it using your own username, it will return a similar JSON object, only this time with your details.
So https://api.github.com/ would be the url you can use to communicate with the GitHub API, and https://api.github.com/users/:username is the url used to communicate with a specific endpoint that will give you a specific user’s data.
Now that we know what an API is, and can distinguish it from the more specific API Endpoint, it’s time to look at what role it plays in a communication network.

From the diagram above, you can see an illustration of the communication between an API and various other components in a network. The server where the API is hosted can be referred to as the API server, and the API’s resources are also hosted on this server. As such, the API acts as an interface to access these resources.
Notice that the API server can also make requests to communicate with other API servers (3rd Party Servers) in order to share data and enhance its own capabilities.
Great… but, so what?
Now that you have a better understanding of what APIs are, it is time we discussed why they are so important, or rather, so useful that they’ve become such an integral part of software development that almost every system has some kind of API.
APIs are used for a variety of reasons, but the most important of all being that they allow systems to communicate with each other and share resources without compromising the integrity or safety of these systems and their data/resources.
Essentially they help regulate access to a system’s resources by providing specific channels and rules upon which these resources can be accessed and used. APIs make this easier in that YOU (as the API creator) define what resources ‘users’ have access to.
APIs can be used for internal communication where by the API endpoints are not made public, but rather are used in a closed system. This is done for various reasons such as security or simply just to limit access to the resources. In any case, the API developer has some reason for this.
Some organisations (like Google and Facebook) make some of their APIs public, allowing 3rd parties (like us) to consume them. This is quite useful for ‘us’ third parties as those APIs allow us to add more functionality to our applications with minimal effort. Saving us a great deal of time in that we don’t have to re-implement a solution that already exists, we can simple use it.
For instance, say your application needs to have some kind of map system that gives directions. You’d probably spend several months creating this system and, as it scales, spend even more time trying to optimize it.
Luckily there is no need for you to re-implement a mapping system. or write your own algorithm that finds the “best path”. You could instead use the Google Directions API which already has all of this functionality implemented, you simply need to use it.
You make a request to the API, passing some parameters such as an origin point, a destination point and a mode of transportation (driving, walking, transit,etc) and it will return a path which you can plot on their map.
So rather than spending several months trying to implement some kind of mapping system, you just spend less than a couple of hours setting up a means to communicate with an already existing solution.
So in a nut shell, to answer the question of “Why we use APIs”, the simple answer is that they provide convenience and allow us to save many months of development and produce better quality software at a much faster rate.
To take stock:
Now we know what APIs are, what role they play in a communication network, and why they are such a vital part of modern software development.
End.
I hope you found this blog post useful and thank you for reading. I’d like to hear from you, so please leave a comment down below. This post is the first of a series on APIs I am writing. In the next one I won’t tell you what API is, we’ll build it.