Understanding REST, gRPC, GraphQL, and OpenAPI to build your APIs

Whether you're implementing a microservice architecture that will be scalable and resilient or forward-thinking for interoperability possibilities, APIs provide the essential level of abstraction that enables communication between separate pieces of software.

Modifying an API architecture once it is live is no small feat, so taking the time before building one to identify your needs and goals for your API is a worthwhile step that will help you create the API you want.

During the last two decades, new architectural styles have emerged to improve communication between different software. In this blog post, we take a deep dive into APIs and how they work before looking at four popular API architecture styles: REST, gRPC, GraphQL, and OpenAPI. In our comparison, we will consider their unique benefits, limitations, and typical use cases.

• The core of APIs: enabling communication between different softwares
• REST: The common ressource-based architecture for APIs
• gRPC A high performance, open source universal RPC framework
• GraphQL: A query language for your API
• OpenAPI: a specification for machine-readable interface files for RESTful web services

The core of APIs: enabling communication between different softwares

An API, or Application Programming Interface, enables two software applications to communicate with one another.

Essentially, APIs are logical contracts between client requests and server responses. When one software needs to communicate with another software, it makes a request. Once the other software receives this request, it returns the programmed response.

Building on this definition, Web APIs enable software to communicate with other software across the internet. Web APIs facilitate this by establishing an agreed upon manner to exchange data between clients and servers; this agreement is the implementation of a Web API architecture.

A web API is also the abstraction layer that lets different types of devices, like mobile and desktop computers, interact with your servers. Moreover, it is thanks to web APIs that you can interact programmatically with apps, such as Koyeb, Stripe, Twitter, and more.

To ensure interoperability between clients and servers, there must be an agreed-upon manner to exchange requests and responses between clients and servers. This mutual understanding is achieved by using a standard web API architecture, be it REST, gRPC, GraphQL, or OpenAPI.

REST: The most common architecture for APIs

REST is a resource-based API architecture design that uses:

• URIs for objects the API interacts with,
• HTTP methods to perform operations on those resources.

REST, an acronym for REpresentation State Transfer, has six guidelines for creating reliable and stateless web services. First, there is a uniform interface that uses a resource-based naming convention between clients and servers that remain decoupled. Moreover, communication is stateless with REST, and HTTP caching is used to reduce load on the server and improve overall network efficiency. Services that implement these REST principles are called RESTful services.

Common Practice for Public APIs

REST is a popular choice for building:

• Public APIs and management APIs,
• Backend web services,
• Resource-driven apps that do not need flexible queries.

Benefits of REST

There are several benefits to the REST architecture:

• Flexibility and scalability due to the separation between clients and servers.
• The ability to cache reduces user-experienced latency.
• Since REST is a mature architecture, there are many resources that make it easier to learn compared to newer architecture styles.
• REST supports multiple data formats like JSON, XML, and CSV.
• Responses in JSON are human readable, which make it great for external facing APIs.

Limitations of REST

There are several considerable issues with the REST architecture.

• Over-fetching: Since REST responses are all inclusive, responses may return more information than needed.
• Under-fetching: On the other hand, sometimes multiple roundtrip calls to different resources are required to obtain all the desired information for the client.
• Large payloads: REST returns large responses in JSON or XML, which are heavier than binary serialization formats like protocol buffers.
• Versioning: With a REST design, APIs have versions for each change. It can be challenging to keep track of what data each API version can return.
• Service discovery: Clients need to know the location of each service, which is a complicated problem to solve. If you want to learn more about this issue, we wrote about service discovery and how it solves the communication in distributed architectures in a previous blog post.
• Theory versus practice: REST is simple in theory, but in practice it is quite difficult to design a web API that is 100% REST. That's ok! Your use case may need you to break from the REST guidelines.

gRPC: A high performance, open source universal RPC framework

Another API architecture model is RPC, or Remote Procedure Call. Unlike in REST where the addressable entities are resources, the addressable entities in RPC designs are procedures.

With gRPC, clients can call methods to a remote server as if it were a local object. As defined by Martin Nally in this Google blog post, gRPC a technology for implementing RPC APIs that uses HTTP/2 as the underlying transport protocol.

gRPC was created to solve key challenges that arise when building an API, such as optimizing data serialization and network communication. Authentication, load balancing, monitoring, access control, and more are all built-in features or available to add to your API with plug-ins.

A noteworthy component of gRPC is its use of Protocol Buffers. Protocol Buffers is Google's open-source mechanism to serialize structured data into a binary message format. This binary format is smaller than other serialization formats like JSON or XML, which speeds up the time data can be sent across the internet.

Powerful internal APIs

gRPC is used by Koyeb, Netflix, CoreOS, CockroachDB, and many more to connect distributed architectures. Here are a number of use cases where gRPC shines:

• Internal APIs: gRPC is a great choice for server to server communication,
• Event-driven systems: For real-time communication with streaming calls within a microservice architecture,
• Multi-language microservice architectures: You can use gRPC in microservice architectures composed of services written in different languages since gRPC is language neutral.

gRPC background

Now a part of CNCF, gRPC is a framework that was originally developed by Google and Square. Google's internal RPC framework Stubby inspired Square's networking and microservice framework Sake, which they built to improve communication between mobile clients and their services. When Square heard Google was open-sourcing Stubby by creating Arcwire, the two teamed up to create gRPC.

Benefits of gRPC

A hugely cited benefit of gRPC:

• Speed: milliseconds matter because each client request takes time and that time can compound creating negative user experiences.
• Scaling: the binary format of protocol buffers enables Google to scale at the levels it does.
• Polyglot: gRPC is language neutral, so you can use your preferred languages.
• HTTP/2 transport protocol enables powerful features:
  • Multiple calls via the same channel,
  • Connections can be bidirectional, meaning requests and responses can be sent at the same time,
  • High-performance streaming for real-time communication.
• Efficient for mobile and IoT communications: with smaller payloads and less CPU intensive exchanges thanks to the binary format of protocol buffers.
• Versioning: easier than REST with backwards compatibility and sensible defaults.

Limitations with gRPC

Some of the considerable limitations with gRPC include:

• gRPC does not have browser support. While this problem is actively being addressed, for the moment you need to use a proxy.
• Protocol Buffer responses are returned in a not not human-readable format,
• Steeper learning curve compared to REST. Learning how to use Protocol Buffers is more difficult.

GraphQL: A query language for your API

GraphQL is a server-side runtime and API query language that is best used alongside another HTTP API architecture, like REST. This means your choice of API architecture would not be between GraphQL or REST, but rather between REST with GraphQL or REST without GraphQL.

After using REST APIs for years, Facebook developed GraphQL to remedy the issue of over-fetching data and create more resource efficient queries. Today, GraphQL is governed by the GraphQL Foundation.

GraphQL is a powerful abstraction that decouples the request from the response by passing them through a single endpoint: /graphQL.

When getting started with GraphQL, you want to start by making a schema registry of all the queries you can make with your GraphQL API and all the types those queries will return. That way, when you make a request to the server, it returns the expected response. This precision optimizes payloads making it a powerful querying solution.

Use GraphQL to push beyond the limitations of REST architecture

When you feel the limitations of REST, you can use GraphQL to create new API architectures. Most typically, people use GraphQL for external-facing APIs and to make querying more flexible. As Jeff Lombard so nicely synthesizes in his blog post, you can use GraphQL to:

• aggregate data from multiple sources and put it into one API,
• add functionality to an old API,
• simplify a complex API by adding GraphQL as a proxy API.

Advantages of GraphQL

There are several key advantages to GraphQL:

• Query language: GraphQL's query language lets you define the data you want, solving the over-fetching and under-fetching data problem.
• Smaller payloads: Since you can specify the information you want to request, payloads are smaller compared to all-inclusive responses experienced with REST architectures.
• Scalability: GraphQL is designed to be highly scalable.
• Client libraries: GraphQL integrates with several client libraries including the ReactJS UI framework.
• No versioning: you have a single version of the API that evolves and gives continuous access to new features.
• GraphQL's detailed error messages simplifies debugging efforts.

Limitations of GraphQL

On the other hand, there are some considerable limitations to GraphQL:

• Learning curve: There is a steep learning curve for GraphQL given its unique schema definition language (SDL) and niche operations, like query, mutation, and subscription for real-time notifications from the server. Moreover, schema building is challenging and requires strong typing in the SDL.
• Caching: Since caching is not built-in to GraphQL, being able to cache responses requires a custom caching solution.

OpenAPI: a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services

One way to design an RPC API is to use a specification language. OpenAPI Specification (OAS) is a standard specification format for REST APIs that is based on Swagger Specification.

When using OAS, you define how the API will work by configuring either a YAML or JSON file. With OpenAPI Specification, you can define: the resources of your API, like the properties and data types; endpoints; operations; parameters; and authorization.

With OpenAPI, clients interact with the API by building URLs with OpenAPI URL path templates, calculating parameter values if any, and plugging that parameter value into the URL path template and sending an HTTP request.

Machine-readable API definition documents

According to its GitHub page, OpenAPI is used for API definition documents that are machine-readable. You can use OpenAPI for:

• Communication between services of different languages,
• Microservice communication that needs to scale,
• Creating Mock APIs.

OpenAPI background

In 2016, SmartBear Software contributed the OpenAPI Specification to the OpenAPI Initiative, a vendor-neutral organization that now oversees the project.

Advantages of OpenAPI

• Decouples API from implementation
• Mock APIs: Specifications enable you to create mock APIs
• Documentation: Create spec-driven documentation that cover how your API functions.
• Mature and large community: large tech giants and growing companies alike contribute to the OAS because having a standard industry format to define REST APIs is valuable. This makes this specification stable.
• Language-agnostic: it is human and machine readable.

Limitations of OpenAPI

• Known limitations: Not all services can be described by OpenAPI, nor does it support all possible style of HTTP APIs.
• Not a magical solution: When designing an API, you should use OAS to help you create your API rather than rely on it to magically create your final API product.

Deploying your APIs on a Serverless Platform

Whenever you're building an API, you'll want to take the time during its design phase identify your project's constraints and needs in order to determine which architectural style you should build with.

Then, once your API is ready to be pushed into production, deploying it on a serverless platform like Koyeb is a resourceful way to save engineering time and maximize the efficiency of cloud computing resources.

Koyeb is a developer-friendly serverless platform built to be the fastest way to deploy apps globally. Regardless of which web API architecture you choose to build for your application, you can deploy on Koyeb and benefit from its array of impressive built-in features, like its CDN and global edge network, autoscaling, private network with service discovery and mesh and automatic TLS encryption, and much more.

Sign up to deploy your API today! Read our documentation to get started and join our community to talk to us and stay up to date with the latest updates.