Hands-on with GraphQL
Introduction
Recently, I have given GraphQL language a try, and wanted to share all the things I learned along the way. The sole purpose of this article is to give the basics of the language, as well as demonstrate the fundamentals in a demo project. I am hoping that you’ll have a good hands-on experience.
History
The language has been developed by Facebook to serve the mobile clients and had been open-sourced in 2015. The Specification has been maintained by the GraphQL Foundation.
GraphQL is a query-based language, that runs on the server as an API, which essentially focuses on querying the data by the client-given-criteria in a single API call. In simple terms, we can think of this as composing a Select Query in SQL, with the fields from the tables we would like and then having the engine returned the output in a single response. Needless to say, GraphQL is not limited to query, but perform CUD operations as well.
Terminology
The terminology can go deep as much as it can. We will focus on the basics and concepts to get us started with gaining hands-on experience with the language.
In addition, in the demo project I have prepared, you can open the GraphQL Schema definition file called “schema.graphqls” and view all the details.
Schema
Schema is a structure and the definition of data that is provided by the API. Schemas can be safely assumed like a POJO class in Java. The clients will know what to query and fetch the fields they wish to. The detailed information can be found on the GraphQL’s Specification page. A schema can be defined like this:
Queries
Queries are the means for clients to request data from the server. The magic of GraphQL appear here. The client only asks for the fields that they require for a given Schema. The back-end is responsible of providing this set of query known as “Resolver”, that resolves the expected data and attaches it to the response. The detailed information can be found on the GraphQL’s Specification page. Queries can be defined like this:
Mutations
Mutations are known to be means to alter data on the server. We can relate Mutations to the CUD operations and R can go for the queries. The detailed information can be found here. Mutations can be defined like this:
Subscriptions
Subscriptions are long-lasting data-fetching operations that are initiated between Client and Server. An active connection is preserved between both parties and Server keeps pushing the new data sets to the client from what we know in Socket protocols. The detailed information can be found here. Subscriptions can be defined like this:
Advantages and Disadvantages
Let’s lay some of the good and bad parts of this language. I have concluded some key points that may help you decide when you are designing your system architecture.
Advantages
- GraphQL defines the schema for Clients and Server to agree on the same contract,
- Client calls to the GraphQL API Server are handled in a single round-trip and clients only retrieve the portion(s) of data requested. This gives a great deal for preventing network latency issues,
- Comprehensive composite queries (if we are to fetch different resources e.g. Products and Reviews) can be concluded in federations by using some open-source tools like Apollo GraphQL federation. We can identify this issue in REST and common pattern to resolve Back-ends for Front-ends — BFF in short
Disadvantages
- In-depth and complex queries can be cumbersome for clients and can introduce some bugs for back-end, while processing corner case scenarios,
- Client-side caching on the HTTP level can be a bottleneck, you can read about the detailed post on Stackoverflow,
- Rate Limit Implementation can be problematic and you may need to rely on commercial tools.
Demonstration
I have prepared a demo project using Java 17 and Spring Boot. In this project, we will work on sample Cryptocurrency data sets to illustrate all the operations in the GraphQL language. The source code can be found in my personal GitHub repository.
Furthermore, we can try out the following examples using a nice and useful UI tool comes out of the box. Once you fire up your Spring Boot server, head to the following URL locally.
When performing the examples on the UI tool, I strongly recommend you to play around with the fields. While executing queries, add and remove of them to have different outputs.
Queries
Queries can be implemented and executed in some various ways. Lets see the first way, that will allow us to query all the historical data sets.
Back-end Controller Binding Method
Query Code
Query Response
This way we will retrieve all the historical prices available in our system. What if we want to query by a specific symbol? Well, for that purpose, we can use the following specific query:
Back-end Controller Binding Method
Specific Query Code
Specific Query Response
Mutations
As mentioned, mutations are the means to manipulate the data on the server. We will execute the following query to insert a new historical price entry for an Alt coin.
Back-end Controller Binding Method
Mutation Code
Mutation Response
Subscriptions
Earlier we have assumed, that the Subscriptions operation works as a Socket Protocol. To demonstrate the demo properly. I’ve hooked the back-end method to connect to Binance’s Trade Web Socket, so that we can have a real-life simulation.
In order to run the Subscription on the client-side, open the following link locally, then you will see that the JavaScript client will automatically subscribe to our GraphQL subscription endpoint automatically, then the data will start flowing.
Back-end Controller Binding Method
