Things used to be simple. An API was the “interface” with your application programs. Entering punch cards at a terminal? That’s your API. First generation of graphical user interfaces controlling hardware? That’s your API.
Now when we say API, we largely mean the web APIs that have unlocked the internet as we know it. These are the standards by which different applications and services share data and ensure streamlined experiences to users across the globe.
Common API Types
Today, most development teams use REST APIs, gRPC, or GraphQL to deliver API functionality. All three of these allow easy communication between services, or from a user interface or device to an upstream service.
While many of the features of these technologies are similar, there are some differences that are important to know when building atop them—and even more important when testing them for security.
In this post, we’ll discuss the key features of REST, gRPC, and GraphQL APIs and which projects each API type is best for.
REST (Representational State Transfer) APIs are based on HTTP and use standard HTTP actions such as (GET, POST, PUT, DELETE, etc). Calling a REST API typically requires the combination of an action, an endpoint URL, and data payload—usually in JSON or XML format.
We typically talk about APIs as RESTful when they comply with a certain set of standards. Interestingly enough, many REST APIs today only comply with a subset of these. Three of the key standards are:
- Stateless: REST APIs are stateless, meaning that each request contains all the information needed to complete that request, and the server does not store any client context between requests.
- Cacheable: REST APIs can be designed to be cacheable, allowing clients to cache responses for better performance.
- Uniform interface: REST APIs use a uniform interface, which makes it easy to understand and use them.
Because REST is an architectural style, rather than a hard and fast set of standards, it’s often difficult to determine how compliant (or RESTFul) an API truly is. Measurements like the Richardson Maturity Model help with this challenge.
Originally built by Google, gRPC (Google Remote Procedure Call) is a high-performance, open-source, RPC (Remote Procedure Call) framework that is used to build fast and efficient APIs. gRPC uses protocol buffers for data serialization and it supports multiple programming languages.
Some key features of gRPC include:
- Bi-directional streaming: gRPC supports bi-directional streaming, which means that both the client and server can send multiple messages to each other in real-time.
- Binary serialization: gRPC uses protocol buffers, a binary serialization format that is more compact and efficient than text-based formats like JSON or XML.
- Service definition: gRPC uses a service definition to define the interface and methods of the API, making it easy to understand and use.
GraphQL is a query language for APIs that was developed by Facebook. GraphQL allows clients to specify exactly what data they need and how it should be formatted, and the server returns only that data. GraphQL queries are written similar to traditional database queries, helping the technology gain wide adoption quickly.
Some key features of GraphQL include:
- Flexible queries: Clients can specify exactly what data they need using a flexible query syntax. This reduces latency and improves performance.
- Strongly typed: GraphQL uses a strongly typed schema to ensure that clients and servers are in sync and prevent compatibility issues.
- “The code is the documentation”: GraphQL APIs are as self-documenting as they come, making it easy to understand what a query is doing.
Which type of API is best?
All three technologies are used to build APIs, but they have different use cases and advantages.
As the oldest of the three, RESTful APIs are widely used and well understood, making them a de facto choice for many web applications. However, the common implementations of REST APIs don’t always offer optimized performance for today’s needs.
gRPC is ideal for microservices or other use cases where performance and scalability are key. However, gRPC requires using a proxy like gRPC-web to communicate with the browser, which can add complexity to implementation.
GraphQL helps streamline data transfer, by making it easy to retrieve specific data points as opposed to large data sets. This unlocks flexibility in when and how API calls are made, which can lead to performance improvements.
Ultimately - there’s no “right” or “better” choice. The right approach is the one that provides the right balance of usability, speed, and scalability—and of course security and reliability.