Since Roy T. Fielding published the basics of RESTful services, also known as REST, in 2000, these APIs have been very popular in the design of distributed systems. Despite many advantages a REST-based interface is not always the best choice.
In 2015, GraphQL was launched, which is an interesting alternative to REST APIs. This article gives a brief overview of how GraphQL functions compared to REST and presents some usage scenarios.
What is GraphQL?
GraphQL is a query language for APIs which also provides a server-side environment for the execution of queries. GraphQL was developed by Facebook and published as open source.
A GraphQL API essentially consists of two components:
- Schema: describes the relevant data of an API as well as its relationships; the schema is created on the server using its own schema definition language (SDL)
- Query language: is used by clients to request data from the server; the client can specify here, which data it wants
Our application case: an actor database
Our fictional scenario is an actor database. This database (server) managers information about actors and films and offers an interface for the retrieval of this information through different applications (clients). For simplification purposes, we will assume that the clients retrieve existing data and do not write new data into the database.
A classic REST API
We start with a classic REST API and consider the following endpoints / resources: ACTORS and FILMS. The REST URLs look like this:
If a client is interested in both the information about an actor and the filmography, two API calls are required. It is a prerequisite that the ID is known. The server delivers all data which have the attributes ACTOR and FILMS. The communication between the client and server could look like this:
… and a GraphQL API
The schema of our GraphQL API consists of the two objects (also called types) ACTOR and FILM and looks like this:
In contrast to REST, the client can specify here in the request which attributes it wants. If the client is only interested in the attributes SURNAME, NAME and FILMS (with TITLE and DIRECTOR) of each actor, it could formulate the query like this:
The server would return exactly the requested data, not more and not less.
In our scenario, the GraphQL server has one endpoint. Therefore, the client only needs one request to access all the data. The communication between client and server looks like this, in simplified form:
GraphQL API: Usage scenarios
Unlike REST, in a GraphQL API, a single request to the server is sufficient to receive all the relevant data. This has the advantage that in particular, clients with fluctuating or poor network connection are relieved and communication can be made a little more stable. A concrete example for this are mobile clients, which are connected via one of various radio technologies.
Furthermore, clients of a GraphQL API can specify exactly what data they would like. This is of advantage when the server has to serve multiple clients and the clients need different information from the data model or use different versions of the API.
GraphQL vs. REST?
A GraphQL API offers clients more flexibility than the traditional REST API. Here, the client is clearly in the foreground. In certain use scenarios, GraphQL is a useful alternative to REST. However, GraphQL is by no means “a better REST”. It merely follows a different concept. As any other technology, GraphQL also has some disadvantages. It is a unique ecosystem. Also, depending on the implementation, GraphQL can also increase the load on servers. The use of GraphQL should therefore always be well though through and tailored to the specific scenario.
Author: Nicolai Zaidman
Blog - Technologie & Innovation
Migration to an AngularJS application – Refactoring to TypeScript and Angular5Read now