The Complete Beginners Guide to Understanding APIs

Introduction

Communication has evolved drastically since the invention of the internet on January 1, 1983. In the 21st century, blatantly referred to as the "social media era," information is conveyed efficiently and in real-time through the internet. On that premise, APIs play a role in information sharing and transmission.

From sending messages to your friends or family on WhatsApp to reading tweets on Twitter, checking the weather forecast, or scrolling through your Google feed, you benefit from the power of APIs.

What Is An API

Despite existing years before, the first definition of an API was made in 1990 by Carl Malamud, who defined it as;

A set of services available to a programmer for performing certain tasks.

Fast forward to February 7, 2000, at the IDG Demo conference. Cloud computing company Salesforce, Inc launched the first modern API, the Salesforce API.

An API is a medium through which two or more applications use requests and responses to communicate simultaneously. A client sends requests to a server; the API delegates them to the server. Eventually, the server sends back a response through the same API to the client.

What observations do we make? The communication is indirect, with the API acting as the "middleman". During transmission, we only interact with the API layer that links the endpoints; in this context, an endpoint is a URL that provides the location of a resource on the server.

The communication is indirect with the API acting as the "middleman".

Check out the illustration below and the following simple examples to understand this concept.

Example 1: Ordering food at a restaurant through a waiter.

Example 2: When signing up or logging in to DEV.to, you have social sign-on (SSO) options using apps such as Google, Facebook, Twitter, etc., to authenticate your details.

What Happens During the Single Sign-On?

Common in many apps nowadays, single sign-on is an authentication method which enables users to log in to a session once, using one set of login credentials. It allows a user to access the app securely during that session without logging in again.

During SSO, the social media server (which contains user authentication details) communicates with the app using OAuth, an authorization protocol to grant permissions.

When you click the "Sign in with Google" button, a request is dispatched to the Google server through the Google API. The server or database verifies your credentials and then responds to the client through the API, which gives you access to the site or app.

Let Us Break Down The API Further

The API stands for;
A — Application. P — Programming. I — Interface.

• Application — software with a distinct function.
• Programming — writing instructions that tell the computer the tasks to perform.
• Interface — the contract of service between two applications.

Applications are web browsers, mobile apps, IoT devices, and company servers or databases. Programming instructs the APIs on what tasks to perform, i.e. what endpoints to access and given inputs. The requests include GET, POST, PUT, PATCH, and DELETE, which segues into the interface through which everything happens.

Developers use APIs to hide complexity, organize code, and design reusable parts. Products and services hence communicate with others, providing an abstraction layer.

When designing new products or managing existing ones, APIs give you flexibility, simplify design and administration, and provide opportunities for innovation. However, a developer must obtain an API key that uniquely identifies the app accessing its endpoints before use. We will discuss them further down in the article.

---

Types of APIs Based On Use Case

Private APIs

Also referred to as "internal APIs," they are strictly accessible within an organization. Due to their restrictiveness, they streamline data transfer between different systems and are highly secure, efficient, and traceable.

Newly introduced systems can seamlessly integrate with these APIs.

Public APIs

These are the most common types of APIs. They are also known as "open APIs" since they are accessible to anyone who wants to utilize them in an application.

They exist in two models;
1. Free
2. Subscription

The latter is based on the number of requests per specific quota. For example, when appeals to the server exceed 10,000, the developer has to pay a subscription fee.

Open sharing of data encourages integration with various apps, i.e., Uber and Google Maps API.

Partner API

These are only accessible by authorized clients with whom you have a business relationship. Due to the stringent measures set, security is at a high level.

Composite API

Composite APIs combine multiple requests into a single API call. For instance, to create order within a shopping cart, you need to access numerous endpoints;

• Create a customer
• Create an order for the customer
• Add item 1 to the order
• Add another item
• Change the order status

Due to fewer API calls, they have lower server load times, resulting in faster systems. Mainly used in microservices, one job may need data from many internal APIs to complete, thus encouraging simplicity.

Types of API Protocols

REST APIs

REST stands for "Representational State" and is a web-based API that responds with data in JSON format. JSON is a lightweight text format for storing and transporting data.

Example of JSON-formatted text:

{
"first_name": "James",
"last_name": "Kamau",
"age": 25, 
"car": "Toyota Mark X" 
}

REST APIs are easier to use than the rest and hence preferred for beginners. JSON is reliable due to its scalability.

SOAP APIs

They use a protocol (the Simple Object Access Protocol) and transmit data in XML format. Due to its stricter protocols, it is more powerful and secure than REST.

RPC-Based APIs

These APIs invoke processes written with XML or JSON.

GRAPH QL

According to GraphQL's official website;

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

This API receives requests from a client and strictly sends back queried responses. This model appropriately utilizes resources, making it faster, more flexible, and developer-friendly.

It is preferred by businesses and organizations when building APIs because it helps them develop apps faster.

WebSocket API

WebSocket APIs allow a bidirectional interactive communication session between the browser and a server. This API enables you to send messages to a server and receive event-driven responses without querying the server for a reply.

---

Securing and Authorizing REST APIs

REST APIs are the most commonly used since they run on the web and send and receive HTTP requests from remote servers.

Applications use these APIs to display data fetched remotely. Before you can receive these requests, the API needs to authenticate your app to avoid security breaches that may culminate in server hacking. With that said, there are two main ways that you can secure and authorize REST APIs;

1. API Keys — API Keys verify the program making API calls to a server. They identify the application and ensure it has the access rights needed to make that call. They are not as secure, which is where the Authorization tokens come in.
2. Authorization Tokens — Authorize users to make API calls. The tokens authenticate the users to verify if they are the actual users and have the access rights to make the calls. They work like stamped tickets. The user retains access as long as the token remains valid. However, the token is invalidated once the user logs out or quits an app.

Importance of APIs

Below are a few reasons why APIs are essential;

1. Access to critical information — Clients can access information thanks to the power of APIs.
2. Process Automation — Process automation uses software and technologies to automate business processes and functions to accomplish organizational goals. APIs play a massive role in this.
3. Save time and resources — Time is an essential resource. With APIs, developers can save time. Instead of building features from scratch, they can integrate third-party APIs into their apps to provide various services. It saves time and improves performance.
4. Data integration — As discussed above, APIs help integrate data to communicate between apps. Google Maps data is used in the Uber app to allow for a seamless experience between the driver and the customer.
5. Acceleration of customer service — Businesses use API services to acquire customer data from external servers. That would have taken a long time, i.e. searching for customer details using APIs takes less than 2 seconds. The same would take a long time without the help of APIs. That results in increased customer satisfaction and hence boosts customer-business relationships.

Examples of APIs

Since the invention of APIs, many have developed various use cases. Some examples of APIs are;

1. Google Maps API — Google Maps is a great example and a commonly used API in our daily lives. From requesting Uber rides to getting directions to your nearest coffee shop etc., you use the Google Maps API.
2. Weather API — The Weather API is utilized in most applications to show you the forecast for the week/month. With this, you can plan your day, know what to wear etc.
3. Pay with M-PESA — M-Pesa is a digital payment platform in Kenya. It allows customers to pay for goods and services online, i.e. when shopping for a TV. You can pay via M-Pesa, which is possible through the M-Pesa API.

---

API Documentation

Before using an API, you need to read its documentation which details the services offered and how to utilize them, covering everything one needs to know for practical purposes.

High-quality API documentation comes in handy to developers, improving development speed. They can either be auto-generated using tools or written manually. Excellent API documentation encompasses the following;

• Simple explanations in easy-to-read English.
• Code samples to explain the functionality.
• Accurate and up-to-date documentation.
• Solutions to all problems the API can solve for the users.

Endpoints, together with inputs to use to get the desired results are major points within API documentation.

Example: If you want to use the DEV.to API, you need to know how to acquire an API key and know the endpoints to use to, say, get medium users, posts, publications within a specific topic, and dates published, among other details. Details such as pricing are also vital since most APIs have a free tier based on the number of requests made.

Conclusion

APIs play an essential role in our daily communication via the internet. Given the many scenarios demonstrated in the article, you will point out APIs used the next time you use apps on your phone.

In the following article, I will build a simple Android weather app using the OpenWeatherMap API.

See you at the next one.

Peace ☮️✌️