How to choose between REST vs. GraphQL vs. gRPC vs. SOAP

Bruno Pedro

June 29, 2023

To create the Postman Open Technologies Knowledge Base API, I’ve been following our team’s internal API design playbook, which covers the strategy, definition, validation, and specification of an API. After finishing the strategy phase by interviewing potential API users, I’m now in the definition phase, where the goal is to document what the API will offer.

The first thing to identify during the definition phase is the API architectural style, which encompasses the design principles and constraints that define the structure and behavior of an API.

Here are some of the most popular API architectural styles:

• Representational State Transfer (REST): A stateless, client-server communication model centered around resources identified by URIs (Uniform Resource Identifiers). Interactions using this architectural style use standard HTTP methods (e.g., GET and POST).

• GraphQL: A style that allows clients to retrieve just the data they need in a structured way. It reduces over-fetching by enabling clients to define the shape of the returned data using a query language.

• gRPC: A high-performance RPC (Remote Procedure Call) that works with a binary serialization format called Protocol Buffers. It uses HTTP/2 for maximum performance and works with various programming languages.

• SOAP (Simple Object Access Protocol): An XML-based messaging protocol that defines a set of rules for running APIs. SOAP can use different transport protocols, such as HTTP and SMTP.

So, how do you know which architectural style to use? In one of the Knowledge Base API project meetings, GraphQL was considered a good candidate because of its versatility. However, I wanted to know more to understand why the API consumers would want to use a GraphQL client. Ultimately, I wanted to align the choice of API architectural style with users’ needs.

Create a compatibility matrix: align your API with users’ existing tools

I identified a simple framework to help me identify the best architectural style to use. I went back to the information I had obtained during the interviews and compiled a list of all the tools that potential consumers were using regularly. Whatever the architectural style I choose, it must be easy for users to consume from those tools. The architectural style must also be a good fit for the data and operations I’m designing. With this simple framework in mind, and equipped with information from the interviews I had done before, I was able to create the following compatibility matrix:

Along the x-axis, you can see the different architectural styles. I split REST into a variant for reading data and another for creating data. I did it because many tools make it easy to read external data but not so much to create it. Along the y-axis, you can see all the tools that I compiled from the interviews with potential API users. With this table, I can identify the compatibility between each architectural style and each tool. Some of the compatibility cells are not perfect, meaning that some add-on or third-party tool is needed for the connection to work.

The information from the compatibility matrix above showed me that the architectural style that best adapts to all the popular tools is REST. Almost all the mentioned tools let users read from external REST endpoints. In addition to that, REST is a good fit for the type of data and operations that I’m designing. The Knowledge Base API aims to provide statistical reports by accepting queries that can take multiple parameters. In other words, the shape of the returned data and the nature of the input parameters is consistent with what’s available in the REST architecture style.

To summarize, it’s important to align your decision of which API architectural style to use with what potential users need. To do that, you can find information about the tools they use. You can then create a compatibility matrix where you identify what tools let users access APIs with different architectural styles. From that, combine the best match with the internal data and operations you’re designing. Ultimately, your choice of architectural style should be the one that offers better compatibility with users’ suite of tools and is the best fit for your data and operations.