In this blog, we study several API styles: the REST-style (Representational State Transfer), the REST-like style, GraphQL, Falcor, the RPC style (Remote Procedure Call), the SOAP style and gRPC. We compare the approaches, show advantages and disadvantages, commonalities and differences.
APIs can basically be realized using any of these styles. How do we know, whether a particular style is appropriate for a given API? Which style should we choose for our cool new API?
RESTful API Style
REST (Representational State Transfer) is an architectural style for services, and as such it defines a set of architectural constraints and agreements. A service, which complies with the REST constraints, is said to be RESTful.
REST is designed to make optimal use of an HTTP-based infrastructure and due to the success of the web, HTTP-based infrastructures, such as servers, caches, and proxies, are widely available. The web, which is based on HTTP, provides some proof for an architecture that not only scales extremely well but also has longevity. The basic idea of REST is to transfer the ideas that worked well for the web and apply them to web services.
HATEOAS is an abbreviation for Hypermedia As The Engine Of Application State. HATEOAS is the aspect of REST, which allows for dynamic architectures. It allows clients to explore any API without any a priori knowledge of data formats or of the API itself. According to its definition, the REST style requires HATEOAS. I have studied a well-known API that does a decent job in following the HATEOAS principle.
REST-like API Style
There is a large group of APIs, which claim to follow the REST style, but if you analyze these APIs more closely, they actually don’t. They only implement some elements of REST, but at their core, they are RPC APIs (see below).
To analyze REST-like APIs, the Richardson Maturity Model may be helpful. It allows gauging how big the gap between the REST-like APIs and complete REST actually is. It distinguishes levels 0 – 3, with only level 3 being proper REST. The lower levels 0 – 2 are in fact RPC style. However, people typically speak about REST services, even if only levels 1 or 2 are reached. REST at levels 1-2 is sometimes called “pragmatic REST” or “REST-like APIs”.
One of the limitations of the REST style with its focus on resources is that it does not natively support events.
GraphQL API Style
For a long time, REST was thought to be the only appropriate tool for building modern APIs. But in recent years, another tool was added to the toolbox, when Facebook published GraphQL, the philosophy, and framework powering its popular API. More and more tech companies tried GraphQL and adopted it as one of their philosophies for API design. Some built a GraphQL API next to their existing REST API, some replaced their REST API with GraphQL, and even others have ignored the GraphQL trend to focus single-mindedly on their REST API.
But, not only the tech companies are divided. Following the discussions around REST and GraphQL, there seem to be two camps of gurus leading very emotional discussions: “always use the hammer,” one camp proclaims. “NO, always use the screwdriver,” the other camp insists. And for the rest of us? Unfortunately, this situation is confusing, leading to paralysis and indecision about API design.
The intention of the Book on REST & GraphQL is to clear up the confusion and enable you to make your own decision, the decision that is right for your API. By having the necessary criteria for comparison and general properties, strengths, and weaknesses of the approach, you can choose if the hammer or the screwdriver is better suited for your API project.
Falcor
Falcor is similar to GraphQL, it introduces a virtual layer that can be used to map frontend requests to backend services.
The basic idea is to create a virtual JSON resource, which is actually used as a container. This virtual JSON resource is published under a URL address. We then link data from various backends and data sources into this virtual JSON resource. The virtual JSON resource is all-encompassing and is designed to be extended over time. As a result, the virtual JSON resource is pretty big.
Clients should not need to retrieve it in its entirety, so similar to GraphQL, the client can specify which part of the resource is interesting and only that specific part should be retrieved.
RPC Style
RPC is an abbreviation for Remote Procedure Call. RPC is an architectural style for distributed systems. It has been around since the 1980s. Today the most widely used RPC styles are JSON-RPC and XML-RPC. Even SOAP can be considered to follow an RPC architectural style.
The central concept in RPC is the procedure. The procedures do not need to run on the local machine, but they can run on a remote machine within the distributed system. When using an RPC framework, calling a remote procedure should be as simple as calling a local procedure.
SOAP (RPC API Style)
SOAP follows the RPC style and exposes procedures as central concepts (e.g. getCustomer). It is standardized by the W3C and is the most widely used protocol for web services. SOAP style architectures are in widespread use, however, typically only for company internal use or for services called by trusted partners.
gRPC (RPC API Style)
gRPC is an efficient RPC implementation. It has a language-neutral and platform-neutral specification, and SDKs for many languages and platforms, so it can be used widely, for communication across platforms and languages. gRPC is super fast and efficient because it uses Protocol Buffers (protobufs) to serialize the service- and message-data into binary streams (and deserialize), the HTTP/2 standard for optimized binary transfers, and bidirectional streaming to avoid (long) polling and blocking HTTP calls.
Wrapping Up
The most common API style is REST over HTTP. This is why one can assume in practice that APIs are realized with the REST style. Want to learn the REST-Style for API Design? Check out the RESTful API Design Book.
Want to learn more about “When should I use which API style”? Check the API Architecture Book.
Also published on Medium.
