To REST or not to REST? GraphQL vs REST

GraphQL vs REST

GraphQL is the opposite approach to REST, and this is no accident. There are fundamental differences between the two that determine the mindset and direction of development. Let’s take a look at the most important ones.

Endpoints

Endpoints implementation is one of the most significant differences between the two architectural styles. While REST requires multiple endpoints for accessing and altering various kinds of data, GraphQL utilizes only one. On the one hand, it simplifies backend development, which in turn reduces maintenance costs and helps mitigate security risks. On the other hand, it deprives us of some built-in features of HTTP.

Originally, REST wasn’t tied to specific transport protocols; however, it is associated with HTTP, its request methods, and response codes. It’s a blessing and curse at the same time: Typically, it comes with a multitude of free features—caching and relatively simple file uploads—but it also tightly binds the application with a specific transport implementation.

GraphQL doesn’t use response codes or HTTP methods, which makes it transport- and application-layer independent, but it also requires more effort to implement basic things such as caching.

Client- vs server-driven design

Using REST, there is no way to pick what data is returned from a specific endpoint. The other side of communication faces the same problem: The client has to send data to the server in the predefined form.

These aspects are what critics view as the main drawbacks to REST. Retrieving all necessary data often requires multiple requests; meanwhile, the form of passed data is always defined by the server, which inevitably leads to excessive data transportation and processing.

GraphQL solves this problem by using its own query language called Schema Definition Language (SDL). It’s used to define which exact parts of data on the client side are to be sent by or changed on the server.

SDL is considered human-readable. Here’s a simple example of what a GraphQL query can look like:

query { 
  user (id: 1) { 
    firstName 
    secondName 
    age 
  } 
}
                  

It is of course another full-fledged language with its own strict rules and syntax, but it’s definitely more understandable than REST’s combination of endpoint names, HTTP methods, parameters, and request body.

Development speed

It’s not easy to determine which approach is easier to implement. On the one hand, REST with its established practices, benefits from tight collaboration with HTTP, and dozens of established patterns lends itself to kickstart server development. On the other hand, being a server-driven approach, REST requires a lot of work on the client side in adding support to all endpoints and processing responses.

At the same time, GraphQL might require more work on the server side for initial implementation, but further extending its implementation is easier and thus cheaper—especially on the client side. Additionally, there’s no need for API versioning or supporting new endpoints. Any API update is a matter of adding a field to a SDL query.

Openness

This difference isn’t necessarily a defining one, but it’s important to note. REST is not a protocol—it’s an architectural style described in constraints and requirements. It has endless ways of implementation and dozens of widely used frameworks. It’s practically impossible to initiate changes in REST.

At the same time, GraphQL is a precise standard. Moreover, it’s now open source and managed by a non-profit organization under The Linux Foundation, so its evolution can be influenced.

Advantages of GraphQL

All GraphQL advantages stem directly from its differences from other styles. Here are the most notable ones.

Control over fetching

As mentioned, the client controls what is fetched from the server. The server sends exactly the requested portions of data: There is no “under-fetching,” which occurs when necessary data has to be retrieved with multiple consecutive API calls. There’s no over-fetching either when the server sends extra information that has to be filtered on the client side. Thus, no excess time and hardware resources are spent on data sending and processing. Besides the better user experience, GraphQL can save the organization money, too.

Less communication overhead

This might sound controversial, but while using GraphQL, front-end and back-end engineers don’t need to communicate that much. When programmers depend on each other, the result is often an overhead to the scope of the work. In the GraphQL world, there’s no need for constant requests for new API or questions about how to retrieve a specific piece of information.

Data-type safety

The GraphQL schema strongly defines the types associated with each piece of data. It helps mitigate the risks of receiving an unexpected value somewhere in the middle of a response. Data validation is simpler, which leads to fewer bugs and a better user experience.

Self-documentation

Apart from the relative simplicity of the SDL syntax, GraphQL is self-describing and doesn’t require a lot of external documentation, which cannot be said about RESTful systems. REST requires documentation for all possible requests, responses, and HTTP codes in detail.

Lack of versioning

Discoverability is optional in the REST standard and usually ignored because it’s not trivial to implement. As a result, clients and servers are tightly coupled: Changes on servers are bound to affect their clients. A partial solution to the problem is API versioning.

With GraphQL, versioning is normally not needed. If we have to add a new field to the schema, we’ll do it. Older clients can either use it or not because all fields are optional. Therefore, the lack of versioning saves us the headache of updating clients to newer API or maintaining older versions.

Disadvantages of GraphQL

Unfortunately, every technology has its downsides GraphQL is no exception—it comes with its cons that render its use inapplicable in certain cases.

New technology

While REST comes with a vast knowledge base and great community support, it has fewer followers.

The prevalence of REST results in a great number of frameworks and libraries that can be used as a base for a server implementation. GraphQL certainly has its own share, but objectively it’s still a drop in the ocean.

Lack of caching

Unlike REST, GraphQL is not coupled with HTTP or other specific means of transport, so it lacks the benefits derived from such an association. Caching is undoubtedly one of the most notable examples.

A single common endpoint means that there are no unique identifiers to the data we fetch; thus, we don’t get built-in caching features that come with operating systems or browsers. We must implement our own means of caching or place our trust in a third-party library.

Vulnerability

More trust in client applications leads to more vulnerabilities. Clients are able to make especially complicated requests, which require convoluted database queries on the server and—if we’re not careful enough—might lead to performance hiccups. This is especially relevant to open APIs, where unknown clients, out of recklessness or malice, can launch a denial of service attack.

Conclusion

Considering the above, GraphQL works nicely for distributed systems, where both the client and the server are under the organization’s control. If a project is started from scratch, GraphQL can help it grow quicker. It’s perfect for applications that mainly retrieve and mutate data stored on a remote destination.

Conversely, due to design limitations, GraphQL is not ideal for projects that take advantage of caching or with applications whose main functionality is uploading files. GraphQL is further inappropriate for small systems that exchange little data between components—setting up a GraphQL runtime for them can be overkill.

Alternatives

For cases where neither REST nor GraphQL works well, the industry suggests alternatives. A notable one is the SOAP protocol. It’s no longer used widely because its communication language, XML, is not the best candidate for transferring data by a network. However, SOAP remains an interesting technology that forces service discovery and allows a dialogue between the server and the client.

SOAP evolved from an even older technology of remote procedure calls (RPC). This technique involves calling parts of a remote application as if through a local function call. Such an approach makes sense in action-centered applications (as opposed to resource-centered ones). The most famous example of RPC frameworks is Google’s gRPC.

GraphQL is not one of its kind—a number of frameworks and protocols have attempted to implement a similar mindset. One of them is GROQ, while another is Netflix’s Falcor. They might have their own advantages, but they are even less commonly used and both lack a support community.

While this is not an exhaustive list of available architectures, it should give you an idea about the variety of existing approaches. In the most sophisticated cases, it can make sense to use more than one—for example, some backends implement GraphQL schema for simple data transfer and use a separate server with a limited set of REST API endpoints for file uploading and downloading.