GraphQL: API Client Validation

I believe most of you are familiar with the good old REST API. I'm using it in most of my applications. The concept of REST API is rather fine but it has its issues.

The most frustrating part about writing REST API for me was communicating with front-end developers. I was always struggling with documentation for the APIs I’d built. There are many options, including Swagger, RAML, and many more. All of these utilities are rather good but every one of them requires a lot of attention and a lot of writing. Even if the developer creates good documentation, there is always human error that leads to inconsistencies between documentation and actual implementation.

A year ago I came across GraphQL —, I found it very interesting and thought that I had to explore it more. Later, I started a project in which I decided to use GraphQL. When GprahQL API was implemented, I started working on front-end setup. Then I discovered something that blew my mind. GraphQL has a library called **GraphiQL that exposes endpoint for exploring the GraphQL API((. With GraphQL the developer can access the schema from the server, which is actually documentation for the latest version of the API.

After doing some research for various things I can use the exposed schema for, I discovered a plugin for WebStorm and Intellij. The plugin validates GraphQL syntax against exposed schema from the server. This allowed me to save time that in the past was wasted on documenting REST API, but I had to go further.

I managed to adapt the plugin I discovered in my front-end part. This plugin works with template literals that are part of ES6. First I had to connect this with my server in order to work. All I had to do was to modify the plugin's config file (graphql.config.json) by changing the url and replacing it with my server url.

The next part was a little bit weird. This plugin is searching for a template literal named graphql. So I created a function named graphql that sent the request to the server.

export function graphql([query]) {
  return (variables) => {
    let body = {
      query: query,
      variables: variables
    };
    return fetch('/graphql', {
      method: 'POST',
      body: JSON.stringify(body),
      headers: {
        'Content-Type': 'application/json',
        'authorization': localStorageService.getItem('AUTH_TOKEN')
      }
    }).then(response => response.json())
  }
}

This function accepts query as a parameter which is GraphQl syntax, and returns a function that can accept GraphQL variables and make requests to the server.

The final part is putting this function, combined with the GraphQL plugin, into action. Every request that is made to the server is implemented like the following example.

const getById = (customerId) => graphql`
  query getCustomer($id: String!) {
    customer(id: $id) {
      id
      user {
        id
        email
        name
        surname
        referral
      }
    }
  }`({id: customerId});

The fascinating thing here is, while I write this GraphQL query, I have validation and autocomplete for GraphQL syntax.

Also, when API is updated I get errors in my IDE where I have invalid queries.

For this setup I use GraphQL server written in NodeJS, WebStorm and ES6, and ESNext syntax for JavaScript. It is a limited setup but it’s worth a try. After some more research I found plugins for Visual Studio Code and Atom.

GraphQL for VSCode
language-graphql
atom-graphql