Everything You Need to Know About APIs: A Beginner’s Guide

9 min readNov 30, 2024

Everytime I read an article on API, they give the restaurant analogy, which i have grown to be tired of. So, I want to approach this article from a different angle, and a variety of analogies.

Think about all the times you’ve logged into an app using ‘sign in with google’. Most times, this saves your memory load because you don’t even remember the passwords you used to sign up for these apps. Because you have a google account and google has your data already, The app’s API asks google “Is this person really who they say they are?” and then receives a “Yes” or “No” before signing you in.

APIs work just like that. An API (Application Programming Interface) is a means for different software applications to talk to each other and share their “parts.” They share parts in the sense that they have rules that allows one software to request information or services from another.

Why are APIs so cool?

APIs are the reason why apps work together, because they allow for smooth communication across different applications. It enables them to exchange data and do useful things, without you needing to see all the work happening behind the scenes.

Without APIs, you would have to enter the same information into every single app you use. But that is not all, because APIs give room for innovation, customization, reusability, saves time and reduces errors in apps. A few real-life examples:

Google Maps: When you see a map in an application like uber or chowdeck, know that they did not build their own maps. They use Google Maps’ API to get map data, and then display it for your use.
Weather Apps: Many weather apps don’t have their own weather sensors. They use APIs to get real-time weather data from trusted sources and show it to you. So Instead of software developers building a weather tracking app from scratch, they can use an API to get data from a weather service.
Social media Login: As I mentioned earlier, when you use your Google, Apple or even Facebook account to log into a new app, the app uses an API to talk to Google or Facebook. The API asks for your authentication details and then awaits a “Yes” or “No” to verify your identity.
Payment Processing: When you pay for something online, your credit card information goes through a payment processing API. It securely verifies your payment and confirms the transaction without exposing your card details.

How Do APIs Work?

To understand how APIs work, think of them as a set of rules for getting answers. Imagine asking a librarian for a book. You tell them the book’s name (the request), they tell you how their books are arranged so that you could search for it (processing), and you go ahead and find the book (response). Here’s a breakdown:

Request: Your app or software sends a message to another app, asking for data (such as your account info) or a service (like a request to display map).
Processing: The other app receives the request, gathers the data you need, and prepares the response.
Response: The app sends back the information you requested for. If you asked for the weather, it returns the current temperature, wind speed, and whether it’s sunny or rainy.

The Categories of API You Might Come Across

Even though they have the same primary action, not all APIs are the same. Some of them include:

Open APIs: These are APIs available for anyone to use. Developers especially, use them to add features to their apps. For Instance, Twitter API lets developers access tweets, which is why some developers are able to create AIs like roastmyprofile.
Internal APIs: As the name implies, these are used within a company, and only people in the organization can use them. They help different parts of the company’s software communicate with each other, such as a company’s internal HR system for accessing employee records.
Partner APIs: These are shared with specific partners. They are not open to the public, but are available to trusted partners. Think of a payment gateway API that partners with a shopping website. Once you attempt to make payment, it leads you to a site like Paypal, Paystack, Stripe, e.t.c.
Composite APIs: They let you request data from multiple places at once. For example, An online travel site that gathers flight details, hotel availability, and car rentals all in one search.

The Anatomy of APIs

Endpoint: This is the location where an API can access the resources you need. Endpoints are always in the form of a URL. Let’s say you open your twitterapp, the Endpoint twittter uses to load a user’s tweet is the URL.

https://api.twitter.com/2/users/{user_id}/tweets

2. HTTP Methods: APIs often use the web’s standard communication language, which is HTTP (HyperText Transfer Protocol). The HTTP methods tell the API what action to take such as:

GET: to retrieve information.
POST: to send new data.
PUT: to update existing data.
DELETE: to remove data.

So when you scroll through Instagram, the app uses a GET request to fetch the latest photos. When you post a new photo, it’s using a POST request. Here’s a sample API request to delete a tweet.

curl -X DELETE "https://api.twitter.com/2/tweets/1456349734567890123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"

3. Headers: API headers exist just to provide a context to what you are requesting for. This could be extra information like the content type, character length, media type, etc. so that the API knows what to send back.

Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Custom-Header: CustomValue

4. Parameters: Parameters are the extra bits of information you add to your API request. You could call them search filters that help you narrow down the search or specify what you need. Lets say:

https://weatherapi.com/current-weather?city=newyork&unit=metric

Here, city=newyork and unit=metric are parameters. They tell the API exactly what city and unit of measurement you want.

5. Response Body: This is the “answer” you get back after making a request. It’s usually in JSON format, which is easy for computers to understand, but also human-readable.

Here’s what a JSON response might look like after a weather request:

{
 "city": "New York",
 "temperature": "22°C",
 "condition": "Sunny"
}

Popular APIs

Google Maps API: For location data and maps.
YouTube API: For accessing video content, comments, and analytics.
OpenWeatherMap API: For weather forecasts and current conditions.
Spotify API: For accessing songs, playlists, and user data.

How API Architectures Shape Data Exchange

APIs come in different architectures, each with its own way of handling data requests and responses. Knowing them will help you understand how APIs function behind the scenes, and choose your preference. The four common architectures are REST, GraphQL, SOAP, and Webhooks.

REST (Representational State Transfer)

REST is the most popular architectural styles used for web APIs today. It almost seems like it is the only one developers use. It follows a simple approach that relies on HTTP methods like GET, POST, PUT, and DELETE to interact with data. Most REST APIs use JSON or XML formats to exchange data, making them straightforward and easy to integrate.

Example: A weather app using REST might have endpoints like

/weather/today OR
/weather/forecast

to get specific data.

GraphQL

GraphQL, developed by Facebook, is a more recent API query language that is more flexible than REST. Instead of receiving a fixed set of data, GraphQL allows you to specify exactly what information you want. You have the power to decide/customize what the API response should look like.

For Instance, In the same weather app, a GraphQL query might allow you to request only the temperature and humidity for a given city, reducing unnecessary data.

SOAP (Simple Object Access Protocol)

SOAP is a protocol that follows a stricter set of rules compared to REST. It relies on XML for message formatting and has built-in error handling, making it suitable for environments where security, reliability, and strict standards are of priority. SOAP is pretty complex, which makes it the preferred choice for industries like banking and telecommunications that need strong data validation and transactional integrity.

Example: A payment processing service might use a SOAP API to ensure every transaction follows precise standards for security and validation.

Webhooks

Unlike traditional APIs, which require you to constantly request information, Webhooks work by sending data to you whenever an event occurs. They function like “reverse APIs,” where you provide a URL, and the server pushes updates to you as soon as something changes. This makes Webhooks ideal for real-time updates without the need to ask the API continuously.

Example: If a weather service uses Webhooks, you could receive a notification the moment severe weather is detected, instead of repeatedly checking the weather API.

Each of these protocols have their strengths and use cases. REST for simplicity, GraphQL for flexibility, SOAP for strict standards, and Webhooks for real-time updates. Knowing these will help you to choose the right architecture for your API project.

How to Use an API: A Step-by-Step Guide

You don’t have to be a coding expert to understand how to use an API. You only need to follow the instructions that come with it. To start working with an API even if you’ve never coded before, you should:

Find an API you are Interested in: Depending on the project you are working on, there are sites where you can find an exhaustive list of APIs that match your interest. APIs for games, weather, maps, and even entertainment. Websites like RapidAPI and ProgrammableWeb have thousands to explore.
Sign Up and Get an API Key: Once you’ve chosen an API of your interest you need to know that many APIs require a unique key to use. This key is like a password that lets you access the data. Be sure to keep it safe.
Read the Documentation: Every API has a documentation or guide that tells you how to use it. It includes what you can request for, how to ask, the structure, and what to expect in return.
Make a Request: This is like typing a question into a search bar. You could use a software like Postman to send requests and see the response without writing a single line of code.
Read the Response: The API will send back a response, mostly in the JSON format. You can then use this data however you want.
Build Something Simple: Start small. Maybe create a website that displays the vlogs with the highest views on youtube, using an API. Or a site where you rate Netflix movies.

What Can Go Wrong?

APIs are super useful, but they can have limitations such as;

Rate Limits: This is the maximum number of times you can ask an API for information in a certain period. If you send too many requests too quickly, your app might stop working for a while.
Outdated API: Sometimes APIs change, and if your app doesn’t update to a newer version, it can might stop working. It’s like trying to open a door with an old key.
Data Privacy and Compliance: Be aware of the data you send through APIs. If you’re using an API that handles sensitive information (like financial or health data), you need to ensure that it complies with data privacy regulations (like GDPR, HIPAA or the one for your country). APIs that do not handle data securely can lead to compliance issues and legal consequences.
Dependency on External Services. Using an API means you rely on a third-party service. If that service goes down, changes, or gets deprecated, your application could stop working or require adjustments.
Cost: APIs can be expensive, especially if you need access to premium features or exceed the free tier’s usage limits. For example, a map API may allow basic map data for free, but require a paid plan for advanced features like traffic data or geolocation services.

Let’s Round this up with a Case Study

Now, imagine you’re shopping online from an app like Amazon or Jumia. When you search for ‘Aldo shoes for women size 38,’ the app sends an API GET request to the website’s server to find matching products.

This is how cloud-based services use APIs:

Your search is the API request, specifying the product details.
The server sends back the API response with product results, pricing, and availability.
If you add the item to your cart and check out, it sends another API call that leads you to a payment platform.

APIs Make Life Easier

APIs makes your apps work together smoothly, saves you the time, and brings information to your fingertips in seconds. They power the apps you use daily, from social media to e-commerce.

So next time you use your favorite app, remember, an API is probably doing a lot of the heavy lifting. If you’re curious, go ahead and explore them, you might find something cool to build.