[Part 2] REST API components & How to read them

If you missed Part 1 of this 3 part “Guide to APIs” series, check it out here.

In Part 1, you learned about API communication protocols and 3 of the most commonly used ones: REST, SOAP, and GraphQL.

In Part 2, we’re going to get real close and intimate with REST APIs specifically.

Why? Because REST APIs are the most prevalent and user-friendly type of APIs that you’re most likely encounter. As a product manager, you play a pivotal role in working with your engineering team to bring digital solutions to life, and a fundamental part of that collaboration is understanding REST APIs.

So in this essay, you’ll get a break down of REST APIs into their essential components so you can confidently discuss, dissect, interact with, and debug them.

Brief intro to REST APIs

Recall in part 1 that APIs allow two applications to communicate with each other.

REST APIs are a set of rules and conventions that defines a standardized way for requests and responses to be structured and exchanged. It is based on the principles of REST, which is a software architectural style for designing networked applications. You’ll also hear the term RESTful APIs in relation to REST APIs.

Here are a couple examples of RESTful rules and conventions followed by REST APIs (not important to memorize, just to give you an idea of what these rules look like):

1. Client-server: Separation of concerns whereby the user interface concerns (client) are separate from the data storage concerns (server).
2. Stateless: Each request from the client to the server must contain all of the information necessary to understand and complete the request. The server cannot use previously stored context information on the server.

REST APIs make extensive use of HTTP (Hypertext Transfer Protocol) as the foundation for communication between clients (like web browsers or mobile apps) and servers (where the API is hosted). 

The majority of what you need to know about APIs are related to HTTP and it’s components. We can broadly bucket the components into the API Request and API Response:

Components of an API Request and API Response

API Response

Once you send a API request, you’ll receive an API response. This response contains the data or information you requested, as well as metadata about the response itself. It consists of the following components:

1/ Status Code

This is a three-digit number that tells you the outcome of your request. Status codes are like short, standardized messages that quickly convey whether your request was successful, encountered an issue, or faced an error. All status codes are divided into 5 categories but you’ll only really encounter 4 of them:

• 2xx: Success — The API request was successful! e.g. 200 OK, 201 Created
• 3xx: Redirection — The API request has more than one response. e.g. 301 Moved Permanently, 302 Found
• 4xx: Client Error — Some information provided in the request was wrong or missing. e.g. 400 Bad Request, 401 Unauthorized
• 5xx: Server Error — Something went wrong on the server and the request wasn’t successful. e.g. 501 Internal Server Erorr, 502 Bad Gateway

Here are some examples of common status codes:

• 200 OK: Your request was successful, and you’ll find the data you wanted in the response.
• 201 Created: This code typically appears after a successful POST request, indicating that the resource you requested has been created.
• 400 Bad Request: If the API couldn’t understand your request, you might see this code.
• 401 Unauthorized: When you lack proper authorization or credentials to access the requested data, this code appears.
• 404 Not Found: This indicates that the endpoint or resource you’re looking for doesn’t exist.
• 500 Internal Server Error: If something goes wrong on the other island (the API’s server), you might see this code.

Common API status codes

2/ Response Headers

Similar to request headers, response headers provide additional information about the response, such as the type of data you’re receiving (e.g., JSON or XML), the server’s version, and more.

Here’s an example:

Access-Control-Allow-Origin: www.amazon.com
Content-Length: 22
Content-Type: application/json
Date: Mon, 30 Oct 2023 16:32:01 GMT

3/ Response Body

This is where you’ll find the actual data or information you requested. Like the request body, the response body is often in JSON format for easy readability and parsing.

Using the same API example as the one in the request body, here’s what a successful response where the product was successfully added to the database might look like. Notice the API response returned a newly created product_id uniquely assigned to the added product.

200 OK POST https://products.amazon.com/api/2017/add

{
  "product_id": 12345,
  "message": "Product 'Smartphone' has been successfully added."
}

Conclusion

We’ve covered the crucial parts of the API and you now have all the information you need to confidently discuss, dissect, interact with, and debug APIs.

REST API Model

In Part 3 of this API guide, we’re going to apply your new found knowledge into practical use. We’re going to look at a couple of real-life scenarios where you’ll need to apply your API knowledge as a product manager and you’ll learn how to debug errors based on API responses.