What is API?

An API, which is a shortened form of Application Programming Interface, is a service that enables two programs, computers, or networks to interact or talk using a common communication protocol.
For instance, the weather app on your device actually pulls weather information from a central server using an API. The application on your phone will send a request (usually using the HTTP protocols).

Some information that will be sent together with this type of request includes the country or region or state, and the type of request made, and the corresponding server URL. You may also need to include an authorization code depending on the API. We'll talk more about API types later.

The request will then be decoded by the server, and it'll return the corresponding needed weather information if the request was successful. If the request is not successful, an HTTP status code will indicate that together with a corresponding error message.
In conclusion, we make use of one form of API or others on a daily basis. Even without realizing it!


API request example

How does API work?

"Human API" - a person taking and returning orders from you
The working principle of an API is simple and straightforward.
Let's assume you visited a large restaurant where duties are being shared among different workers.

Firstly, you have someone that takes orders from you, he/she then delivers the choice that you made to a cook who prepares a dish for you and then returns it back to the original person that took the order from you. The person then serves you your dish based on what you requested.

That person taking and returning orders from you is an API (lol, human API).
API acts as a middleman between clients and servers. They take requests from clients and return responses from servers.

Below is a diagram of how API works

Why Do We Need APIs?

There are many reasons why we need APIs in our ever-dynamic digital lifestyle. Below are some of the reasons:

  • APIs Assist in Data Management
    APIs provide centralized data management. Just imagine trying to gather the purchase behaviors of customers visiting your e-commerce website.
    There are many ways of doing this, but the most effective method is creating an API that collects customer information that you think would be beneficial for your business. This in turn provides useful data in an organized and manageable format.
  • APIs Saves Development Cost
    Let's go back to our initial weather analogy.

    Assuming that you want to create a simple weather app without using any Application Programming Interfaces, you'll be faced with the huge costs of launching meteorological satellites, building a team that manages, and interpreting different weather information, and heavy fees on hardware and software.

    But by simply using an already existing weather API, all you have to do is just send a request and receive a corresponding response on an already established weather infrastructure. That is definitely going to save a huge sum of money for you!
  • Better Software Integration is Aided by an API
    Have you ever imagined how we can directly import diagrams or icons from Flaticons to our Figma workspace? That's basically because of a simple understanding existing between Figma and Flaticons, which is facilitated by API protocols!

    This would've been a difficult task to accomplish without an API.
    Most web apps, mobile apps, or software that allows you to import components from one source to another run on one form of Application Programming Interfaces or the other. Even your social media apps use APIs to access and save files to your device.
  • APIs Makes Collaboration Seamless
    If you've worked in a collaborative tech ecosystem you'll understand that people with different devices and different operating systems can interact seamlessly without any fluctuation. This is possible because of the heavy work done by an API. You can edit your files on a Chrome browser together with your friend running on a Safari browser without having any issues because of an API that facilitates real-time unbiased communication.
  • APIs Provides Top-notch Security and Control
    Let's use Google as a case study. Just imagine having separate login details for Gmail, YouTube, Docs, Google Maps, etc. You're definitely going to be overwhelmed trying to remember all those logins.

    API eliminates this problem by providing outstanding governance and a login management system that helps you to log in with homogeneous details on authorized platforms without a compromise on security.
    This is one of the most overlooked importance of an API!


    The aforementioned are just a few importance of an API. Now let's move on to the types of Application Programmable Interfaces.

Types of Application Programming Interfaces (API)

We often name REST, SOAP, etc as types of APIs, but that's not entirely accurate. APIs can generally be classified into 4 types.


  • Untitled document- Open or Public APIs
  • Partner APIs
  • Internal or Private APIs, and
  • Composite APIs
  • Let's talk about each of them in detail.
  • Open/Public APIs
    Like the name, Public APIs are available to the public for free. Any developer can access and make and receive requests from them without any restriction. The authorization level in this type API paradigm is usually low, as it's readily available.

    While these public APIs are free, some of them are subscription-based and some are available for free for a certain number of web calls, a good example is Google Map API. That allows you to make 1000 API requests per key for free. You'll be charged for the service when you exceed the limit.
  • Partner APIs
    This is just like using a rooted Android device, you'll have more power on your device than a casual user.
    Back to the topic.

    A Partner Application Programmable Interfaces gives out its API externally, but it's only accessible to users authorized by the organization providing the API.

    The level of security and authorization in Partner API programs is generally stronger than those in Public APIs. It's the API of choice of corporate bodies that needs collaboration with external bodies under strict authorization.
  • Internal or Private APIs
    This type of APIs is developed mainly for use within the shore of the providing organization. It's not available for use to the general public. The developers working for these companies have access to the API programs, while external developers don't.
    Private APIs are highly scalable, maintainable, and traceable as every request and response is being made within the company that offers it.
  • Composite APIs
    Composite APIs is basically an API that bundles multiple requests in a single HTTP call. This type of API can gather information from different servers without the need of making multiple calls, hence, reducing API call time and increasing efficiency.
    This type of API is rampant in the microservice ecosystem, as the load on the server is reduced leading to a faster and more scalable configuration.
Having established the fact that API types are basically four, now let's move on to API architectures.

API Architectures: A Detailed Overview of REST, SOAP, and RPC APIs

In the nutshell, an API architecture is basically a set of rules and protocols that states or outlines how data is received and shared between clients and servers.
Many API Architectures exist, but below are the most known types.
  • REST APIs

Representational State Transfer APIs, popularly known as REST API is basically an API architecture that gives guidelines on how to write easy-to-use, scalable, and highly maintainable API software.
There are many qualities that REST APIs possess that make them very popular in the industry. Below are some of the qualities.

1. Uniform Interface
All requests and responses passed in the REST API Architecture are done using a common communication protocol, i.e the HTTP protocol. They are furthermore formatted to different forms to ensure compatibility between various configurations.
Note, Server responses are formatted in JavaScript Object Notation (JSON).

2. Independent interaction
This may surprise you. The request and responses made in a REST API are not recorded. That means that the request and response calls that you make are completely stateless.

3. Layered system design paradigm
Requests and responses performed in a REST API are formatted the same way, improving overall simplicity.

4. Separation of client and server
This is one of the fundamental rules in REST APIs. The client does the work of sending requests, while backends return responses. A client cannot send a response and vice versa.

  • SOAP APIs

Simple Object Access Protocol APIs, better known as SOAP APIs is one the Application Programming Interface protocol that has stood the test of time.
This type of API guideline states how a request and response are to be made and the type of message needed.

This approach makes SOAP APIs very secure and code-heavy.
It's mostly utilized in the private or internal types of APIs because of the level of security it provides.

  • Remote Procedural Call (RPC) APIs

This is one of the rarest types of API. You'll hardly see companies use this type of API even though its design paradigm is straightforward.
The main reason behind the declining use of this API is because of its low-security level. Though some companies still use them for making multiple basic web calls.

What is API Specification and Definition?

API Specification basically provides detailed information on how an API integrates and connects with other APIs. It shows what happens when a particular request is made, the expected response, and what happens in case anything goes wrong.

Another vital information contained in an API specification is how the API is designed and the data types supported by it.
The OpenAI specifications on GitHub is a very good example of what API specification looks like.

Though API specifications may look the same as API definitions, they are actually different. The major difference between the two is that an API specification shows how an API works and connects with other APIs in a human-readable format, while an API definition shows how an API works and connects with each other in a machine-readable format.

API Documentation

Just like software documentation, API documentation is the reference manual for API consumers. It shows developers how an API works and how to actually interact with the API parameters.

The selling point of API documentation is great Developers Experience (DX).
API documentation with good code samples in targeted programming languages is guaranteed to sell rapidly.

Let's go back to our weather app example one more time.
Below is an example of how an HTTP request for current weather information is presented in the documentation for easier understanding for developers, of how the API works.
Request
The image below gives the users of the API the response expected when a request is sent.
Source: ©OpenWeatherMap

Examples of Real World APIs


We have thousands of APIs used for accomplishing various types of tasks. Below are some of the most popular APIs used in modern data-driven applications.


1. Google Map API:

Google has spent millions of dollars on research and development of a power map and navigation infrastructures for developers. Some businesses that use Map include shipping companies, delivery, social media, etc. There's no doubt Google Map API is one of the most useful APIs in the world.


2. Twitter API:

This is one of the APIs that I love using. You can comment, like, retweet, and even follow accounts using the Twitter API based on the rules you lay for it. The screenshot and video saving bots you use on Twitter are built on Twitter API.


3. Imgur API:

if you're an avid member, you'll know that Imgur is one of the best places to get the funniest and most outstanding meme inspirations. You can do almost everything you can do on Imgur's website with their API. You can post, share, and even update profile details with this API.


Thanks for reaching this point. Thanks for reading! You Rock!
Check out these youtube videos to have a solid understanding of an API concept.

No pressure, just get an idea out of them.

1 - What is an API? Basic concept
2 - REST API concepts and examples
3 - What Is A RESTful API? Explanation of REST & HTTP
4 - REST API & RESTful Web Services Explained
5 - Web services tutorial: What is a web service? | lynda.com

API requests are often called web calls or http calls. These are the most common names for requests that are going from the client to a server.

You already know that :)
We help ambitious people to get into Tech with no prior experience.