In our previous article we talked on our successful adoption of GraphQL. We will advance the discussion by eluding into the differences between GraphQL and REST APIs in this article.
Just to reiterate on the intro, before we deep dive into differences
- GraphQL is the new frontier in API’s (Application Programming Interfaces) design, and in how we build and consume them.
- It is a Query Language, and a set of server-side runtimes (implemented in various backend languages) for executing queries. It’s not tied to a specific technology, but you can implement it in any language.
- It is a methodology that directly competes with REST (Representational State Transfer) API’s, much like REST competed with SOAP at first.
- GraphQL was developed at Facebook, and it was publicly launched in 2015 — although Facebook used it internally for a few years before.
Some of the Benefits that I would like to remind again
- A query language for your APIs
- Ask for what you need, get exactly that
- Get many resources in a single request
- Organized in terms of types and fields, not endpoints
- Get rid of under & over fetched
So Let’s start with the question, why we need GraphQL over Rest APIs? In order to find answer, we need to think about what API consumers are looking for. While designing the lightweight and loosely coupled architecture, APIs play an important role in communication between various layers, e.g., front-end and data layer. In our experience, the pattern of APIs (transitional e.g., REST vs modern e.g., GraphQL) is important in bringing implementation and performance efficiencies, hence it is important to evaluate and choose the API architecture pattern based on the following benefits:
- APIs to consume and process structured data
- Avoid over and under fetching
- How to avoid multiple roundtrips
- How to better version control our APIs
One of the biggest mistakes we’ve seen building web applications is the pattern of including too much business logic in the application components. There is often duplication of business logic across these systems, and the relationships are rarely clear to the development team. We suggest to follow the pattern, to normalize the data outside of your components so that your client application’s components can be simple and easy to maintain. This is an area where GraphQL shines.
GraphQL vs REST
Let’s revisit our example in the context of invoking API calls. Below diagram shows a traditional API call which causes under-fetching, dependent requests, and multiple round trips. In the traditional API pattern, you would have to make multiple trips to get Article, Author and Category information.
GraphQL can solve the above issues by creating a domain driven structure and consumer is just making one call to fetch the required data as described in the below diagram.
To summarize the above, look at the below diagram —
It is very challenging to maintain versions of a REST APIs. Due to the requirements for backward compatibility your API has to continue supporting old requirements.
There are more dimensions to compare,
- Unlike REST where you might need to have several endpoints to get you the data you need, GraphQL exposes only a single endpoint
- REST works on HTTP only while GraphQL doesn’t need HTTP to work.
- Unlike REST where you can use any HTTP verb, GraphQL recommends using only the HTTP POST verb
- Unlike REST where the request and response are defined by the API, the clients or the consumers of GraphQL can define what data they need. While the size of the resource is determined by the server when working with REST, the API defines the available resources and the client requests only what it needs in GraphQL.
- Both REST and GraphQL are platform and language agnostic, and both are adept at returning JSON.
- GraphQL calls are handled in a single round trip. Clients get what they request with no over fetching and under fetching.
- GraphQL is introspective. A client can request a list of data types available. This is ideal for auto-generating documentation. On the other hand, REST has Swagger, which does not provide detailed description on data types.
To summarize, why to introduce GraphQL when we already have REST?
- A single endpoint
- Tailored to your needs
- Access nested data resources
- GraphQL calls are handled in a single round trip. Clients get what they request with no over fetching and under fetching.
- Strongly defined data types reduce miscommunication between the client and the server.
- GraphQL is introspective. A client can request a list of data types available. This is ideal for auto-generating documentation.
- GraphQL does not dictate a specific application architecture. It can be introduced on top of an existing REST API and can work with existing API management tools.
- GraphQL allows an application API to evolve without breaking existing queries.
Most organizations can’t update all their applications at once so you can’t just turn off your old REST API. A GraphQL server can act as a middleware between your old REST API and your new applications. Update your other consumers apps that use the REST API’s to work with your new GraphQL API in a phased manner. Once all of your clients are no longer using the REST endpoints you can replace the REST API fully with the GraphQL API.
GraphQL Challenges
We talked about the benefits of GraphQL. Let’s talk about the challenges you may face in your project when implementing GraphQL.
Performance Issue
GraphQL gives clients the power to execute queries to get exactly what they need. But what if a client sends a query asking for a lot of fields and resources? You can simply let your users run any query they want. A GraphQL API must be carefully designed; it’s not just about putting it on top of a REST API or a database.
Not suited for small application
GraphQL is the right solution for multiple microservices, you’d better go for REST architecture in case of a simple app. REST can be also a valuable approach for connecting resource-driven apps that don’t need the flexible queries offered by GraphQL.
Caching
In GraphQL, there’s only one endpoint (usually an HTTP POST endpoint) where all the queries are sent. Since each query can be different, it is harder to use this type of caching. To reduce the amount of traffic to the web server, you can use persisted queries with persistgraphql.
Handling File Upload
GraphQL doesn’t understand files, a file uploading feature is not included in its specification. You won’t have to deal with this limitation in case of REST, as there you can POST or PUT whatever content you want to.
Rate limiting
Rate limiting of calls becomes difficult because now the user can fire multiple queries in one call. Also Nested queries in graphql leads to circular queries and can crash the server. Extra care has to be taken.
Learning
You need a greather learning curve for GraphQL implementation i.e., how to set up GraphQL, which library & technology to use, GraphQL schema & field types, etc.. The ecosystem is still evolving so you will have to keep up the learnings.
Conclusion
The architectural decision depends on multiple factors such as application user journeys, type of channels, performance requirements, etc.. Every application has its own requirements, and selection should be made based on these requirements.
In conlucion, Is GraphQL always the right fit? Certainly not; Graphql is great if you want to work in a declarative style because it enables you to select only the information or operations you need. However, depending on your use case, performance requirements, and tolerance for unnecessary complexity, GraphQL could be unfit for your project.
