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.
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 is a resource-based API architecture design that uses:
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.
REST is a popular choice for building:
There are several benefits to the REST architecture:
There are several considerable issues with the REST architecture.
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.
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:
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.
A hugely cited benefit of gRPC:
Some of the considerable limitations with gRPC include:
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:
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.
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:
There are several key advantages to GraphQL:
On the other hand, there are some considerable limitations to GraphQL:
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.
According to its GitHub page, OpenAPI is used for API definition documents that are machine-readable. You can use OpenAPI for:
In 2016, SmartBear Software contributed the OpenAPI Specification to the OpenAPI Initiative, a vendor-neutral organization that now oversees the project.
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.