When starting a greenfield project that requires an API of some kind it is important to take a step back and evaluate the options before diving in. These days there are only 2 real contenders when choosing how to design your API; REST or GraphQL.
What is an API?
API, or Application Programming Interface, is a way of communicating between multiple pieces of software. This communication can be two-way, meaning the ‘client’ (receiver) can also send information back, not just receive it.
What is REST?
REST (Representational State Transfer) is an architectural concept, not a technology, and therefore language agnostic. REST is the default standard for any modern API. It determines the way an API ‘looks’ and how developers interact with your data.
Benefits of REST
- Quick and easy to set up
REST follows a simple principle of defining a route and a route handler. There are many tools and frameworks that let you get setup with a REST API almost instantly and there is zero complex boilerplate code required meaning you can focus on building the product.
- Easy to change technologies
As REST only defines the way data is transferred from the server to the client, it does not matter if you want to change the client implementation. No matter how you retrieve data from a REST API, it will always return the data as you expect it to.
Issues with REST
- Hard to access multiple, linked resources
As a REST response is defined by the server it is unlikely that multiple resources will be returned. For example if you wanted to get a user with all their articles you would have to get the user, and then do another query to get all the articles by that user.
- Traditionally more complex state management for the frontend
As there are no types in a REST API, the client has to manually manage the state on the frontend (usually using a tool like Redux). This can be very time consuming and costly to set up.
What is GraphQL
GraphQL is an open source query language. It was developed by Facebook. Although it is a technology, there are many implementations in different languages.
Benefits of GraphQL
- More frontend flexibility
As it is a query language, GraphQL allows the frontend to request what data it requires. This means it will only ever fetch data that it needs.
- Strongly Typed
To write a GraphQL server, you must write a schema that defines the types of each field available. This means that with a little bit of work, the frontend knows what type of data to expect. Making it much easier to scale the frontend project.
Issues with GraphQL
- Language limitations
Although there are a lot of GraphQL implementations for many different languages, there may not be one for the language you usually work in (you can check here).
- Potentially poor performance
GraphQL suffers from what is known as the n+1 problem. As clients can query infinitely nested relations. For example you can query a user with all their articles, the articles comments, the author of those comments, and so on. There are solutions to this but it is still something that needs to be carefully considered when building an API using GraphQL.