Have you ever coded APIs in GraphQL and wondered how you can transit your large codebases written in REST to GraphQL?

You are not alone.

Our GraphQL journey began in April 2018 under the lead of GraphQL enthusiast Mark Le. We initially spent a few days on learning how it works. During this first phase, we made a list of useful libraries and tested them out. Then, we re-wrote some of the existing REST endpoints to GraphQL. We started writing a small admin-only feature. And we also kept REST endpoints so that we could always go back to them if needed.

Once we had the sample endpoints, we presented them to our team in Singapore to persuade them why we needed to make the transition to GraphQL. Our findings on the benefits of GraphQL are in the sections below. I also had a conversation with our backend engineers to explain GraphQL and how it would be beneficial to us. During this phase, I received some feedback that encouraged me me to investigate better tools to write a robust server. Some of the concerns included: the lack of community support compared to REST, and the fact that we had to rewrite and retest some of the security middleware.

“five person facing laptop” by rawpixel on Unsplash

One thing we needed to decide was migration strategies. For that we decided not to migrate every existing endpoint to GraphQL since, as a startup company, we have to move fast. To avoid disrupting the flow of new feature releases, we chose to start writing some of the non-critical features in GraphQL. After writing a couple of features, we collected feedback from all engineers and summarized the parts we would change. This included improving the file structure, naming conventions, and the middlewares.

GraphiQL: API schema visualizer

While designing endpoints, we found API schema very useful because it forces server-side developers to document specification of APIs, as well as reconsider input and out types. This API schema was even more useful for our remote developers since they are on a slightly different timezone; they often had to wait one or two hours to get clarification on REST APIs from developers from another time zone.

With GraphiQL, you can easily view a list of all the available APIs from a server, and it also shows the required input types and output types. This is helpful for front-end developers because they can easily understand APIs without having to ask back-end developers or read the backend code.

GraphiQL shows available endpoints, and their input and output types

Non-nullable and Scalar type

GraphiQL becomes even more useful with GraphQL types. The two types that we have found the most useful are non-nullable and scalar types. Non-nullable type helps frontend codes to be neater by skipping null checks for every field. It also helps us achieve better user experience by letting the compiler find bugs instead of the clients.

Scalar is a type you can define on your own. These types could be used for basic input validations. For instance, we have some scalar types for URL, Email, Ethereum address, etc. By using these types, we don’t have to write codes for input validations in resolvers.

Selective data fetching

There are a few different types of clients, from web browsers to Android/iOS. Let’s consider a webpage with nice charts, numbers, images, etc. Now, you don’t want to show every image and chart on mobile because the screen is smaller. In this case, if you are using REST API, you need to create another endpoint or send some kind of flag so that the server can return a smaller number of required fields. With GraphQL, the client-side code can define the data that API needs to return so it could be useful for a mobile web app.

“person using Google map” by NESA by Makers on Unsplash

It also allows you to reuse your APIs. In many cases, as a web server developer, you need to write some trivial endpoints that return one or two fields. In some cases these could have been combined to existing endpoints, but this would create additional traffic on the server. Selective data fetching could save you tons of time and make your codebases more concise and more manageable.

Reactivity on the web

Reactivity is essential in achieving a seamless user experience, and GraphQL helps a lot to build this functionality. We have implemented a publish-subscription pattern using GraphQL subscriptions and RabbitMQ. We first started using this pattern for admin-only features, and we are planning to introduce this to other features. This pattern goes really well with Blockchain data interaction; by nature, the data takes some time to be settled on blockchain. Subscribing to this data could increase user experience by ensuring the clients are kept updated.

Directive resolvers

@permissionCheck is a directive resolver

We have used directive resolvers to implement authentication middleware. It is just a wrapper function that is being executed prior to the main resolver function. As you can see in the above code, you define directive resolver in your API schema. This makes code reviews easier.