The Ultimate PM’s Guide To APIs

As a new PM, you’re regularly bombarded with developer jargon. But there’s none bigger than this one.

API - Application Programming Interface

Simply put, an API is code that tells one developer how to use another developer’s code without needing to know what happens behind the scenes...that’s it. Too simple? Ok, since ONLY developers can make use of APIs, let’s dive inside the mind of a developer to understand this once and for all.

What is an API?

Let’s say developer X wrote 3000 lines of code to manipulate dates in 3 different ways.

• 1. Format a date (”YYYY-MM-DD”, “MM/DD/YYYY”, “DD-MM-YYYY”)
• 2. Find the number of days between 2 dates
• 3. Get the current date and time

Developer X wants their peers to utilize this code but no one has the bandwidth to understand 3000 lines of code, just for 3 specific functionalities.

So developer X writes an API, as well as a document to guide other developers on how to use their code and call the right functions without the need to learn the main code themselves.

Here are the functions that will make up the API:

These 3 functions, tell one developer how to make use of the code that the original developer wrote, without the need to know what goes on behind the scenes.

Types of APIs

Offline APIs

This is the example that we just discussed ☝🏼.

• - Developer Y would get a copy of the code that developer X wrote
• - Import that into their project
• - Then call whatever functions that make up the API to execute the desired functionality

When using the code through the API, there is NO network connection needed. This is what makes it “offline”. Although you’ll likely never hear developers refer to this as an “Offline API”, that is what it technically is.

Online API

An online API is an API that is utilized over a network connection. Developers can integrate functions of big tech companies like LinkedIn, Facebook, and Google into their application. For example, using Google Maps to display location, or users’ LinkedIn connections in your app is done through an online API.

However, these APIs are generally not referred to as an “Online API” - even though technically that’s what they are. There are 2 types of ”Online APIs”:

• 1. Open API - An API that is available to the public
• 2. Closed API - An API that is only available internally within the company that developed it

Technical teams usually refer to Open APIs or Closed APIs as “the API” in conversations. So it’s always a good idea to clarify which one they are referring to.

When you hear the term “API” (Facebook’s API, LinkedIn’s API, Google’s API), an “online” and “open” API is what people are referring to.

JSON

When using an online API, data is transmitted in JSON format. We’ll discuss the exact details of the transmission, but let’s first understand JSON.

JSON (pronounced “Jay-sawn”) stands for JavaScript Object Notation. It refers to a format that is used in the JavaScript programming language, when dealing with complex data.

JSON data is always in between 2 curly braces {} , and makes use of key/values.

Here are a couple of useful tools that arrange JSON in a readable format:

https://chrome.google.com/webstore/detail/json-viewer/gbmdgpbipfallnflgajpaliibnhdgobh/related

https://jsonformatter.curiousconcept.com/#

I suggest installing or bookmarking one of these, because you will be seeing JSON data on day 1 of working with developers.

CRUD

It’s really tricky to understand APIs unless you understand CRUD. CRUD describes the capabilities for a feature, and stands for: Create, Read, Update, Delete.

Every feature you build will have at least one of these capabilities. Imagine you were creating a feature where a user can upload a product to a marketplace.

📖  Consider the following stories:

• 1. A user can add details for their product and create a product (Create)
• 2. A user can view their product (Read)
• 3. A user can edit the details of their product (Update)
• 4. A user can delete their product (Delete)

Don't focus too much on how these functionalities will be created. Just recognize what your developer means when they say, "We're building out the CRUD functionality for product upload".

Online API Architectures

Now that we understand:

• - Offline vs Online APIs
• - JSON
• - CRUD

Let’s discuss the most common online API architecture: REST(ful) APIs.

REST(ful) APIs

When someone refers to an API, it’s very likely that the API is built using the REST architecture. Making it a REST API.

REST (or RESTful) stands for Representational State Transfer.

This is the architectural style that developers follow in order for 2 codebases to communicate OVER a network. Backend developers write code to create REST APIs, frontend developers write code to consume REST APIs.

Whenever a web/mobile app (frontend) wants to communicate with a server (backend), it needs to know what it's allowed to ask for, and what code to execute in order to accomplish that.

☝🏼 This is the API.

The communication with a server needs to happen in a specific format.

☝🏼 This is the REST format.

The web/mobile app (client) will send a request. The web server will send back a response.

When someone refers to an API by Stripe, LinkedIn, Uber, or any other company, you are going to be utilizing an API that is served over a network connection using the REST standard. Hence, you are actually using their REST API.

There are several components to a REST API:

• - Endpoint
• - Verbiage or Method
• - Request payload
• - Response body

Endpoint

An endpoint is a URL. And this URL is what the frontend would make a RESTful API call to, depending on the task it's looking to accomplish.

For getting a list of products, an endpoint would look like this:

/products

However, that does not look like a URL ☝🏼 😕

The full URL may look like the following depending on the environment you are using:

• https://mystore.com/products (Production)
• https://uat.mystore.com/products (UAT)
• https://stage.mystore.com/products (Stage)

In conversation, developers would just say "/products" (pronounced "slash products") as a short form. It would be implied that every environment would have that endpoint in the codebase.

Verbiage or Method

Every time the frontend makes a RESTful API "request" to the backend, the frontend also sends a verb within that request.

GET, POST, PUT, DELETE

These are the most common ones that you'll hear when speaking to your developers. Why do we use verbs? REST stands for Representational State Transfer. Which means an API call should work the way we expect it to.

Let's tie the verbs above to the CRUD operations we just discussed.

🆕  Create 👉🏼  POST

👀  Read 👉🏼  GET

🔁  Update  👉🏼  PUT

❌  Delete 👉🏼  DELETE

So when we want to perform a "create-like" operation, we would use the POST method along with our endpoint. When we want to perform a "read-like" operation, we would use the GET method along with our endpoint.

The backend developers are the ones that set the verbiage for each REST API endpoint. They need to make sure it makes sense when a developer reads it in the documentation.

If a frontend developer sees this endpoint: DELETE /api/charge. And this REST API call ends up creating a charge, then that's a poor choice of verbiage on the backend developers part.

DELETE /api/charge when read logically, should delete a charge.

POST /api/charge when read logically, should create a charge.

Request Payload/Querystring

I mentioned that a web/mobile app (client) will send a request to a server. The client will often send data to the server as part of that request. The data can be either a payload or a querystring.

Querystrings are sent in the URL, starting with a “?” and separated by the & symbol.

• 1. The endpoint 👉🏼  /api/user
• 2. The start of the querystring 👉🏼  ?
• 3. The 1st variable + value 👉🏼  firstName=Zeeshan
• 4. The 2nd variable + value (as well as any additional variables) 👉🏼  &lastName=Syed

In full, it'll look like this: /api/user?firstName=Zeeshan&lastName=Syed

Next time you shop on Amazon, notice how the URL changes each time you view a product.

Payloads are sent in JSON format.

The difference would be that you don't see the payload sent in the URL, whereas the querystring is sent in plain sight. Don't consider payloads to be completely secure. Payloads can be viewed using developer tools in the browser.

However to be fair, if you were logging into your account...you probably wouldn't want your password to be visible in your browser's address bar 🤔.

Payloads also allow for a lot more data to be sent.

For POST (Create), PUT (Update), and DELETE (Delete), data is sent as a payload.

For GET (Read), data is sent in querystrings.

Response Body

The web server will send back a response. This response is almost always in JSON format. It used to be in XML format, and occasionally still is.

The response body will contain whatever data is that was requested.

Full REST API Example

So we’ve seen an example of an offline API. Let’s take a look at an online API that uses the REST architecture. Consider the following story:

• - A user can open a bank account

Here’s how the REST API could look:

• 1. Endpoint: /api/account
• 2. Method: POST (since it’s a “Create”)
• 3. Payload: { "userId": int, "accountType": string }
• (a) Since it’s a POST, the request body will be a payload
• (b) Data required will be the user ID and the account type
• (c) userId will be an integer
• (d) accountType will be a string (”chequings” or “savings”)
• 4. Response: { "success": boolean }‍
• (a) The response would simply indicate if the account was created successfully or not

The frontend (client) would be written in JavaScript.

That JavaScript code will send a POST request to /api/account.

The body could be:

NOTE: Nearly all programming languages are capable of working with REST APIs.

Once the request is received by the backend (server), the backend code would be written in a way where it will:

1. Grab the data sent in the payload
2. Create the account in the database
3. Send a response to the frontend (client) indicating that everything went well

Once the frontend receives that response, it will update the UI accordingly.

Conclusion

Although PMs do NOT need to know how to code, understanding technical jargon is vital when working with a development team. It’s not uncommon for PMs to feel overwhelmed with buzzwords and fancy jargon.

So take the time to understand the important ones. API is definitely one of them.

If you enjoy digestible and practical tech content for PMs, follow me on LinkedIn.

‍