How to Create Better APIs Using GraphQL

27 Feb, 2023 | 4 minutes read


Are you tired of working with clunky and inflexible APIs? Look no further than GraphQL! GraphQL has been gaining popularity in recent years for its ability to simplify data fetching and make API development more efficient. In this blog post, we will explore how you can use GraphQL to create better APIs that offer increased flexibility and performance.

Why do we need GraphQL?

Old Habits Die Hard – REST

How to Create Better APIs Using GraphQL

REST as an API architectural style has become an industry standard for designing web services and microservices. It offers great ideas, such as stateless servers and structured access to resources.

However, modern apps are becoming more complex, REST APIs can be too inflexible to keep up with the rapidly changing requirements of the clients that access them. With web apps, microservices, IoT devices, and mobile apps all acting as clients with varying demands for accessing our APIs, REST architecture is beginning to show limitations. It’s becoming increasingly clear that REST was not intended to accommodate these diverse demands, and we’re starting to see drawbacks in our overall architecture as a result. Some of these drawbacks include:

Over and under-fetching resources

When making a call to REST API, we fetch all data related to the resource, whether we need it or not. In this way we use more network bandwidth, and the response is large and complex which adds complexity to the consumer side.

Multiple round trips to get the info we need

When we need to get info about multiple resources, we need to call multiple microservices, this process is slow, and adds response time and complexity on the consumer side.

API Heterogeneity

REST API standardization is hard to achieve in microservice architecture where multiple different teams are involved. Things like pagination can be implemented in separate ways making the consumer’s job harder.

REST does not provide contract and workable documentation by default

Consuming a REST API without a clearly defined contract and agreement can be challenging, as any changes made to the API can potentially break the consumer.

API Versioning

Any change in our REST API can be considered a breaking change, to solve this we implement new versions of our API and we must maintain multiple versions of our API, which makes this an expensive task.

The “New Kid on the Block” GraphQL

How to Create Better APIs Using GraphQL

GraphQL is a query language for our APIs. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need, and nothing more. It was officially released in 2015, the first stable version was released in 2018. The technology is mature enough, it is battle-tested and can be used for production on any project. GraphQL is communicating over HTTP protocol and there are a lot of tools and libraries that are already available that make the development process easier.

GraphQL overcomes all the problems and complexity that traditional REST APIs introduce. Here are some of the solutions that this technology brings to the table:

Allows client to specify the exact data needed

We can granulate the data that the API returns, saving on bandwidth, and making the consuming process quite easy.

Aggregation of data from multiple microservices (API Gateway or GraphQL federation)

It’s relatively easy to use GraphQL and an API Gateway to obscure the complexity of an API. This approach enables consumers to retrieve data for multiple domains, or microservices, with just one HTTP POST request.

GraphQL works with defined schemes and known standards

GraphQL APIs adhere to a set of predefined contracts that detail how clients can consume the API. These contracts establish standard practices for essential components such as pagination schemes, authentication and authorization protocols, and the representation of common data objects.

GraphQL API does not support versions

GraphQL allows for the addition of new capabilities through the creation of new types and fields, without creating breaking changes. As a result, it’s unnecessary to maintain multiple versions of the API.


GraphQL is rapidly revolutionizing the way developers build and ship APIs. The technology is matured and battle-tested so we can start using it in production.

In the Java ecosystem, there are a lot of tools that can help us build better APIs. If your API is consumed by multiple clients like a mobile and web app or multiple microservices that require different responses from our APIs, use GraphQL since it offers better bandwidth usage and we can granulate the response produced by our APIs very easily.

To use the best of the two worlds we can use a combination of GraphQL and REST for a project. It all depends on your data and performance requirements.

Overall GraphQL is a very promising technology that will take over in the near future. We are already using GraphQL to solve all the problems that modern distributed applications bring to the table.