Understanding REST API Principles: A Product Manager’s Guide

While working for a multinational media company, I was part of a team tasked with delivering a service for customers to upload, print, and deliver documents to a specified mailing address. We wanted customers to be able to order products and track their packages all through our application. An initial assessment revealed that everything but delivery could be done in-house.

Instead of building the delivery function ourselves, we decided to outsource it and integrate an existing delivery company’s application programming interface (API). REST, or representational state transfer, architecture was the clear choice. REST APIs have become a critical part of software development. For teams whose core business is developing applications, building peripheral features can be time-consuming and often demands deep expertise in a niche domain. This is where REST comes into play. Rather than spending valuable resources developing a feature in-house, there is likely an existing solution that can be bought and integrated into your product using REST.

Used by 86% of developers, REST is by far the most popular API architecture, according to Postman’s 2023 State of the API Report. The survey also revealed that 46% of organizations plan to increase the time and resources they invest in APIs over the next 12 months.

By bridging the gap between the business and technical worlds, product managers are well placed to orchestrate API creation. A basic understanding of REST API principles and best practices is vital, however, in order to lead teams effectively.

As a product manager with a background in software development, my approach has always involved hands-on solving of technical problems, and I have used REST to achieve success in every role. This guide aims to empower product managers with the foundational knowledge they need to help teams build quality REST APIs.

REST API Key Principles and Best Practices

REST is a software architectural style that defines standards for the design and development of distributed systems, making it easier for them to communicate with one another. The following sections explain the key characteristics of REST APIs and how you can maximize their potential.

Get Familiar With Data Formats

REST APIs often communicate using JSON (JavaScript Object Notation) or XML (Extensible Markup Language) as data formats. Gaining a basic understanding of these formats will enable you to interpret API responses and design effective data structures. In my years working as a product professional, these are the only data formats I’ve encountered when working with REST APIs.

XML is more prevalent in legacy systems and industries with established XML-based standards, such as finance or healthcare, in which it makes more sense for maintaining compatibility with existing systems. JSON, on the other hand, is used for a wide variety of microservices and has become the dominant choice for most modern REST APIs due to its lightweight, human-readable format and its compatibility with JavaScript, which is commonly used for web development. It is widely favored for its simplicity and efficiency. Most programming languages extensively support JSON and it is thus the default choice for many popular APIs, including those provided by social media platforms, cloud services, and modern web applications. I recommend, therefore, that you start getting familiar with JSON first.

To grasp the basics, create simple JSON files to get some hands-on experience, experiment with them, and learn how to represent data. There are many available JSON tools that can help you validate your creations.

Use Resource-oriented Design to Reinforce Statelessness

An important feature of REST systems is that they are stateless: The client and server exist as entirely separate entities and do not need to know anything about the other’s state in order to perform an action. This separates the concerns of client and server, making REST an ideal solution for connecting two different organizations.

Because REST APIs are stateless, each request is treated in isolation; every request from the client to the server must contain all necessary information for the server to understand and process it. The server responds with all the information it has for the given request, so if some data is missing in the response, it’s likely that the request itself was incorrect.

Due to their stateless nature, rather than using commands as endpoints, REST APIs use resources. Think of resources as nouns that describe the object the request is about. Having nouns as endpoints makes it clear what each request does.

Using HTTP methods (GET, POST, PUT, DELETE) to perform actions on these resources means you can simplify your endpoint names, focusing them solely on the resources. In the context of the delivery API, for example, if you want to validate an address, your endpoint should be named /deliveryAddress (i.e., the resource/noun) instead of /getAddress (i.e., the verb), because you are using the HTTP method GET to retrieve the information.

Consistency in resource naming is crucial to making an API predictable and easy to use. If names are inconsistent, it’s harder for developers to anticipate the structure of the endpoints, and it will also be difficult to scale the system. Consistency leads to fewer errors and more efficient integration—pick a naming convention and stick with it throughout the API. For example, if you start with customer for user-related resources, don’t switch to user for a similar concept.

To make integration more modular and precise, it is also important to avoid overloading endpoints. Don’t use a single endpoint for multiple purposes; each resource should have a distinct URL, and each HTTP method (GET, POST, PUT, DELETE) should have a clear and consistent purpose for that URL. For example, it would be bad practice to use POST /deliveryAddress for both checking the validity of the address and for providing suggestions on similar addresses. To avoid confusion, a separate endpoint for providing address suggestions should be built, say, POST /addressSuggestion.

Choose a Clear Path Structure

REST API paths should be designed in a way that helps the server know what is happening. According to best practices, the first part of the path should be the plural form of the resource, such as /customers, so that you enter multiple input parameters. This formatting ensures nested resources are simple to read and understand.

In the media-printing organization, we used the following path structure for our endpoints: api.mediaprinting.com/customers/321/orders/9.

In this example, 321 is the customer ID, and 9 is the order ID. It is clear what this path points to—even if you’ve never seen this specific path before, you and the server would be able to understand it.

The path should contain only the information and specificity needed to locate the resource. Note that it is not always necessary to add an ID; for example, when adding a new customer to a database, the POST request to api.mediaprinting.com/customers would not need an extra identifier, as the server will generate an ID for the new object. When accessing a single resource, however, you will need to append an ID to the path. For example, GET api.mediaprinting.com/customers/{id} retrieves the customer with the ID specified.

Parameters can also be passed via query string. In general, path parameters are used for resource identification, with query parameters being reserved for filtering, sorting, or paginating results. Retrieving the completed orders for a customer might be done in this manner: api.mediaprinting.com/customers/321?orderStatus=complete.

Learn Common Response Codes

Responses from the server contain status codes to inform the client of the success (or failure) of an operation. For each HTTP method, there are expected status codes a server should return upon success:

GET: return 200 (OK)

POST: return 201 (CREATED)

PUT: return 200 (OK)

DELETE: return 204 (NO CONTENT)

As a product manager, you don’t need to know every status code (there are many of them), but you should know the most common ones and how they are used:

Source: Codecademy

Familiarity with these status codes will be helpful when troubleshooting because REST APIs, like any other technology, can encounter errors. This knowledge will enable you to anticipate potential issues during integration and communicate effectively with developers to resolve them swiftly.

Become a Hands-on Product Leader

Understanding REST API principles is critical for every product manager, enabling you to make the right decisions as a leader, communicate effectively with developers, increase your team’s efficiency, and ultimately optimize delivery.

REST’s simplicity and compatibility make it an ideal architecture for creating independent microservices that communicate effectively. By choosing an appropriate data format, creating clean, consistent endpoints, designing clear path structures, and acting on response codes, you can capitalize on the benefits of REST for your API.

As APIs become even more ingrained in the web, implementing the tips and best practices outlined above will assist you in building quality functions that companies will proudly incorporate into their products.