When I visualize building an application, I would think of using React and Redux on the front-end which talks to a set of RESTful services built with Node and Hapi (or Express). However, over a period of time, I've realized that this approach does not scale well when you add new features to the front-end. For example, consider a page that displays user information along with courses that a user has enrolled in. At a later point, you decide to add a section that displays popular book titles that one can view and purchase. If every entity is considered as a microservice, then to get data from three different microservices would require three HTTP requests to be sent by the front-end app. The performance of the app would degrade with the increase in the number of HTTP requests.

I read about GraphQL and knew that it was an ideal way of building an app and I need not look for anything else. The GraphQL layer can be viewed as a façade which sits on top of your RESTful services or a layer which can be used to talk directly to the persistent layer. This layer provides an interface which allows its clients (front-end apps) to query the required fields from various entities in one single HTTP request.

GraphQL - On the Server

On the server side, GraphQL provides a schema language which allows you to construct the domain model. In GraphQL terms, these are 'types.' A 'type' is used to represent an entity such as User, Course, Book, etc. It looks something like this:

Here, each field in the CourseTypeentity has a type indicating the value that it can hold (String, Float, Character, Int, etc). Apart from the Scalar types, a field could also be used to declare the relationship between two types. For example, a StudentTypecan have a field called 'courses' to declare the courses that he/she has enrolled in:

Here the field 'courses' is of type '[CourseType]!'. The array notation is used to indicate that a Student record can have a collection of courses, i.e. a student can enroll in multiple courses (1-to-many relationship). The bang (!) is used to indicate that it's a required field.

Apart from defining types, one is required to specify what can be retrieved using a 'Query' and what can be updated using 'Mutation.'

Here types Query and Mutationare special types. They're not used to define an entity, rather, they're used to specify the operations that you can perform on these entities. For example, allCoursesin Queryis used to declare that the client can use this to retrieve a list of courses (returns [CourseType]). A Mutationtype, on the other hand, is used to indicate the operations that you can perform to update these entities. In the above example, createCourse, createStudent, etc. are the operations that you can perform to add or update records.

All the above types put together come to form the type definition for your schema and it gives a high-level overview of the domain model and the operations that you could perform on various entities. However, the business logic for how the data would be retrieved or updated is not present. To accomplish this, one is required to write resolvers. A resolver provides the implementation that maps to the operations declared in the schema. A sample resolver for the above example looks like this:

The resolvers object contains two properties Query and Mutation. Under these, you would define the various operations that can be performed on the entities declared in the schema. Note that the name of the operations would map to the ones specified in the schema (here allCoursesin type Query and createCourse in type Mutation). The type definitions are independent of the language or the platform that you choose. However, the resolvers are written in the language of your choice; in this case, JavaScript.

The type definitions and resolvers come together to define the executable schema which can then be used to define middleware in a Node + Express environment:

I've used 'graphql-tools' and 'apollo-graphql-express' modules to create the schema and the middleware which would accept incoming requests.

To test the server setup, you could make use of the GraphiQL interface which allows you to inspect the operations declared in the schema, add this:

app.use('/graphiql',
graphiqlExpress({
endpointURL: '/graphql'
}));

The GraphiQL interface provides us with a way to test the operations declared in Queryand Mutationof our schema:

Here, the object notation on the left side allows me to specify the query method and the fields that I need from the 'courses' model (id and name). The response from the server (on the right side) includes only the data that I have requested. Although the resolver itself returns the entire object, GraphQL ensures that only the requested data is returned in the response; thus reducing the size of the payload.

GraphQL - On the Client Side

On the client side, the first step would be to connect to the GraphQL server and wrap the root component with the Provider (ApolloProvider from 'react-apollo'):

Here the GraphQL higher-order function accepts two arguments - the GraphQL query and the view component that has to be updated with the query result. The result of the query response is passed to the component as props (this.props.data).

Next Steps:

I've briefly read about 'Relay' and I plan to experiment with it to see how it can be used to connect to a GraphQL server and compare it to see how it fairs with Apollo.