APIs: A Breakdown for Non Technical Product Managers

As a Product Manager, you’ve likely encountered the term APIs, especially in conversations with your developers or engineers. While you…

As a Product Manager, you’ve likely encountered the term APIs, especially in conversations with your developers or engineers. While you don’t need to be an expert in the technical details, having a foundational understanding is crucial. This knowledge ensures that you can actively engage in discussions with your engineering team, avoiding confusion, and enabling you to explain concepts to stakeholders when necessary.

In this article, we’re on a journey to simplify APIs. It might be a bit long, but it’s definitely worth it. This guide gives you the essential basics, helping you build a strong understanding of APIs and enabling you to make the most of their potential for your product’s success.

Before we get into it…

At its core, understanding APIs is dependent on a foundational grasp of three key elements: clients, servers, and the pivotal language used in connecting them — HTTP.

Clients: Clients are the seekers i.e the ones making requests. They are often devices or applications seeking specific information or functionality from a server.

Servers: Picture servers as the custodians of information, the ones ready to fulfill requests. Servers hold databases, process requests, and send back the requested data to the client.

HTTP (Hypertext Transfer Protocol): Now, think of HTTP as the language spoken between clients and servers. It’s the set of rules that ensures seamless communication. When a client wants something from a server or vice versa, they engage in a conversation using HTTP.

This trio forms the backbone of how data is exchanged on the internet. Clients initiate the conversation by sending requests to servers, which respond with the requested information, all facilitated by the rules laid out by HTTP. Your browser makes HTTP requests to a website’s server every time a new page is loaded and it is something called HTTP methods which are used to tell the server what to do. These methods are also used by APIs.

Now that we’ve got that covered, let’s get right into it!

What is an API?

Application Programming Interfaces (APIs) act as the invisible bridge connecting different software applications and enabling them to communicate and share data seamlessly. An API, is in its simplest sense a technology that connects two systems.

Let me explain in non technical terms using this analogy.

Let’s say you go to a library and are looking for ‘Gifted Hands’ by Ben Carson. But the library is huge and you have no clue where to find this book. Luckily for you, you see the librarian at their desk and a catalogue with the types of books you can borrow. You request for ‘‘Gifted Hands’ from their non-fiction list and the Librarian walks through the labyrinth of shelves to find the book and brings it to you.

Based on this Analogy:

• The library is the database

• The books are the data

• You are the requestor — the application/system looking for information

• The librarian is the API — they take the request back to the database and return information back to the requesting application

• the request for the book is the call made to the API

• the catalog represents the specific format the request has to follow so the API understands it

• The book you received from the librarian is the response

Let’s look at a real-world example.

Whenever you create a new account on an application, you get an option to signup with Facebook or Google. Ever wondered how that works?

Well, Facebook and Google already have your details, so instead of performing the tedious task of capturing every user’s information and verifying the credentials, the app accesses their database through the API to verify your credentials.

When a user chooses this option, the application, instead of manually collecting and verifying credentials, sends a request to the respective social media platform’s API. This API acts as a secure gateway to the user’s data stored on Facebook or Google. With the user’s consent, specific information is retrieved, such as the email address or name, which is then used to verify the user’s identity and create an account on the application.

Types of APIs

APIs can be categorized based on

1. Architectural types

2. How they are exposed

Architectural types also called protocols refer to the structure and design of the API, while exposure types pertain to how the API is made available or accessible. These dual classifications help in better understanding and organizing the varied landscape of APIs.

1. Architectural types

2. How they are exposed

Common API Concepts.

Mastering these fundamental concepts is crucial for a comprehensive understanding of APIs. Once you’ve got these down, you’ll feel more confident talking about APIs with your team and any other stakeholder involved.

1. Requests and responses

The piece of data that you send to the server is called as Request.The piece of data that you get back from the server is called a Response.When dealing with APIs, we utilize HTTP methods to request information. These methods essentially represent the actions we perform when interacting with APIs.

The most commonly used HTTP methods are: GET, PUT, PATCH,POST, DELETE.

GET ➖ You make a GET request to get some piece of data from the server

POST ➖You make a POST request to add a new piece of data to the server

PUT ➖ You make a PUT request to edit the existing piece of data on the server

PATCH — is used to apply partial modifications to an existing resource on a server, allowing you to update specific sections of the resource without replacing the entire content.

DELETE ➖ You make a delete request to delete a piece of data on the server

2. Endpoints

An API endpoint is a digital location where an API receives requests about a specific resource on its server. In APIs, an endpoint is typically a uniform resource locator (URL) that provides the location of a resource on the server.. For an endpoint to be operational, it must be “exposed,” meaning it’s made accessible for calls.

Endpoints in an API can be likened to specific doors in a large building. Imagine the building as the server or database that holds valuable information. Each door, or endpoint, leads to a different room or set of resources within the building. When you, as the user, want something specific, you go to the corresponding door (endpoint) and, upon opening it, you access the precise information or service you need. Just like different doors lead to different parts of a building, different endpoints lead to different functionalities or data within an API.

3. API Documentation

Documentation is like the rulebook that helps us and our engineering teams understand how to use an API. It lays down the rules of the ‘contract,’ explaining what the API can do through different calls. When you read this documentation, you’ll notice that many terms are common across all APIs, thanks to the REST principles. This common language makes it easier to work with different APIs. API documentation typically encompasses vital elements such as:

• Authentication Instructions:Guidance on establishing a connection with the API.

• API Endpoints: An inventory of available endpoints for interaction.

• Resources: An enumeration of accessible resources

• Request Format: Specifications on how an HTTP request to the API should be structured.

• Response Format: Guidelines on the formatting of an HTTP response upon receipt.

• Response Codes: Insights into the response codes embedded in the reply

4. API Calls

We refer to the requests to APIs as API calls. So, when we make API calls, we’re reaching out to a specific point in the API (which we call an endpoint) with the hope that the API will share the information we’re looking for.

Imagine using Spotify. If you want details about a particular album, you’d make an API call to the albums section, telling Spotify which album you’re interested in. Spotify, in return, responds with all the details about that album.

5. Payloads

Sometimes technical folks use the word ‘payload.’ It might sound a bit fancy, but it’s just a way to talk about what the API gives back i.e the Response. In APIs, the payload is the data contained within a request. The description is borrowed from the transportation industry, where a truck carries its cargo (its “payload”) to a location.

Here’s the thing: not everything in what the API returns is important to us. The term payload helps us pick out the valuable information we need from all the other stuff the API provides. The payload is usually delineated with curly braces `{}`, and the request is usually sent as a JSON file.

6. Response Codes:

Every time you get a response from an API, it comes with its own response code, which is simply a number with a meaning attached to it. Here are common response codes you should know.

Status codes fall into four main groups:

• 200s: Everything’s Okay

• indicates a successful request with the correct response.

• 300s: Redirection

• Informs that you’ve been redirected to the right resource.

• 400s: Your Mistake

• Highlights an issue on your end, indicating a problem with your request

• 500s: Server’s Mistake

• Signals a problem on the server’s side, indicating an issue with the processing.

7. Webhooks

Webhooks serve as a notable category within APIs, acting as a sort of “reverse” API. Unlike traditional APIs, which require explicit requests for data transfer, webhooks kickstart data transfer when certain events occur — such as receiving a payment or updating a user’s feed. This unique characteristic proves valuable for automatically initiating a series of subsequent events.

8. Headers

Headers play a crucial role in API communication. When you engage with an API, both your request and the subsequent response from the API include headers. Serving as additional pieces of information, headers accompany your HTTP methods. Some headers are mandatory, while others are rarely employed. These headers enrich communication, offering essential context and instructions that facilitate a seamless exchange of information between your system and the API. They provide crucial details, enhancing the efficiency and effectiveness of data transfer.

9. Authentication

When you want to engage with an API, it’s like showing your ID to enter a club. You need to prove you’re not just anyone but a legit user with the right permissions. This is where authentication comes in.

Similar to logging into your email with a username and password, accessing APIs requires a similar process. Think of it as the bouncer at the door checking your credentials. For APIs accessed by external clients, they receive a VIP pass — a security token and credentials. These act like keys to your API, ensuring only those with permission can enter.

Here’s the key difference:

Authentication: Proves who you are (like showing your ID).
Authorization: Specifies what you’re allowed to do once inside.

Now that you’ve gotten a good grasp of APIs let’s see what they can be used to do.

1. Development of Front-End Interfaces: As a product manager, APIs enable your front-end developers to pull data from servers. This is invaluable when creating interactive user interfaces.

2. Integrations: APIs facilitate seamless integration between different software systems. For instance, as a product manager, you can integrate your e-commerce platform with a third-party payment gateway API to enable smooth and secure online transactions like your shopping platform integrating with Paystack or Flutterwave to process payment from customers.

3. Access to Third-Party Services: APIs empower your product to interact with external services.Let’s say your app requires mapping or location-based features.Integrating with Google Maps API allows your app to access and provide accurate mapping services, including real-time navigation, location tracking, and geolocation-based functionalities.

4. Data Retrieval: APIs are instrumental in fetching real-time data. If you’re managing a Live scores sporting application,Leveraging sports data APIs such as ESPN API or TheSportsDB API enables your app to fetch live scores, game statistics, and updates for various sports, keeping users informed during live events in real time.

5. Automation: APIs allow for task automation. Imagine automating routine processes within your product, like sending automated notifications to users based on certain triggers using a notification service API.

Congratulations you made it this far!

In closing, Understanding APIs is like having a superpower for product managers. It enhances your capacity to collaborate seamlessly with development teams. A thorough understanding of APIs allows us to effortlessly integrate advanced features from external applications, enabling continuous evolution for our products. This knowledge serves as a strategic asset, empowering us to make informed decisions, thereby ensuring the competitiveness and adaptability of our products in the market.