GraphQL server using Clean Architecture and Functional Programming — Part 1

Part 1 — GraphQL

Photo by Nicolas Picard on Unsplash

After 8 years of developing Android applications, I decided to enlarge my skills and started to work on backend development.
I started by learning GraphQL on the server-side, then the problems started, how to make a maintainable project without complexifying too much the code?

In this series of 3 articles, I will try to show you:

Part 1: Why I chose GraphQL (over REST)?

GraphQL server using Clean Architecture and Functional Programming — Part 1

Part 2: Which architecture did I choose to be confident in the maintainability of the project?

GraphQL server using Clean Architecture and Functional Programming — Part 2

Part 3: How to reduce the boilerplate introduced by the architecture?

GraphQL server using Clean Architecture and Functional Programming — Part 3

What is GraphQL?

GraphQL is an alternative to REST. Initially designed by Facebook in 2012; it is now open-source.

It provides a more intuitive way to perform complex queries to a server.
Unlike REST, you can ask for the exact resources you need.

If you want to know more about GraphQL, you can go to the official website of GraphQL: https://graphql.org/

What are the advantages of GraphQL over REST?

Documentation

REST API requires minimal documentation.

At least you need to describe:
- which are the endpoints available
- which parameters they can accept
- which kind of value will be returned (date format, enumerations, nullability, etc…)
- what are the HTTP response code and their meaning

Maintaining this documentation can be painful, and most of the time, the front developers have to discover this information by themself.

In GraphQL, all this information is structured in a GraphQL schema.

Similar to SOAP WSDL or GRPC service definition (the ProtoBuffer file), this file describes:
- what are the possibles operation(query, mutation, subscriptions)
- what parameter they can accept
- which kind of value will be returned

This schema is shared between the server and its client. And using a single endpoint, it will allow a front developer to discover by itself all the possible operations.

The maintaining of this “documentation” is no longer painful as it is intrinsic to GraphQL (no external tool is required) and acts as a contract/definition of your server (your GraphQL server cannot work without it).

Data model inconsistency

REST API is very flexible on the data returned.

Depending on the programing language used, you could have inconsistency in the data model.
Some languages don’t handle the nullability easily, some don’t even have a clear distinction between number and string…

For example, in JS:

This behavior could break the client application as they can’t predict which type is lastLogin.

Also, maintaining a REST server over time can introduce a lack of data model naming coherency.

In some endpoints, user_id becomes userId then userId becomes userID, etc…

The GraphQL Schema IDL forces us to maintain a certain coherency as we can reuse and nest the objects (hence the Graph in GraphQL).

Resolver independency

Now, it’s an advantage for the GraphQL server developers.

In GraphQL, you can nest your data (it’s actually recommended), and each field asked by the client will be resolved independently.

So, you don’t have to compute data that won’t be used by the client, and the client can ask for as much data as wanted.

For example, using this query:

A first resolver will return the field email and displayName of the specified user. Then, a second resolver will return each field for an owned home.
And, for each lease of a home, a resolver will return its data.
Finally, for each renter, a resolver will return its id and displayName.

Using GraphQL, you just need to create one resolver per data limiting the code required to create a large server API.

Implementation

To illustrate how we can implement a GraphQL server, we’ll use a small API example.

We’ll use an Apollo-Server running on Express.js. This is just a sample, the concepts work whatever the framework you will use.

This project is currently not applying the Clean Architecture concepts. So, let’s fix that in the next step.

Conclusion

GraphQL server is really easy to implement!
And we’ve seen it has very good advantages.

In a second part, Clean Architecture concepts will be introduced so a more complex project can be easily maintained.

Source code

mbiamont/functional-graphql-server