GraphQL Best Practices

January 25, 2018


GraphQL Best Practices

GraphQL, a Query Language is gaining rapid popularity. It is always a good idea to learn community accepted standards:

# Disabling GraphiQL in Production Environment

One of the most popular features is GraphiQL. It allows testing the APIs right in the browser without having to use any third party resources like PostMan. Also, a client can use this to get accustomed to the API and its various endpoint results. Though this is a boon for both client and server developers, it can turn into a curse if a silly mistake like not turning off GraphiQL is committed in production. This restricts intruders from getting a free access to your API. Thus, GraphiQL must always be disabled in production environments.

# Multiple Platform Support

Since GraphQL isn’t dependent on either front or back end. It makes sense to configure the API purely independent. To do so, the only question you need to ask is will the API still work for the client if the backend platform changes (e.g. From mysql to mongoose)? Keeping this question in mind helps while prototyping and scaling the API for future application upgrades.

# GraphQL API Versioning

Obviously, there’s no harm in versioning the APIs, but with GraphQL, you won’t really find a need to do so. Most of the times, APIs are versioned to alter features or data formatting. In REST, such changes can break the current API and probably that is how the system of versioning came into existence. But as with GraphQL, client explicitly requests the data it wants; versioning new API features doesn’t really make any sense.

# Folder Structure

Keeping the GraphQL horizon in mind, it becomes evitable to keep to functionality discrete in terms of GraphQL schema and operations.

# Precise Descriptions

GraphQL may seem easy to learn and use. But its usage can become really complicated once application scales and complexity get involved. Thus, it is always a good practice to utilize the description attribute for stating the exact thing a type, query or mutation performs.

# GraphQL Mutation Best Practice

Things to keep in mind while defining mutations:

  • Mutation Names – Mutation names must be easy to relate.
  • Precise Logic – Don’t try to fulfill too many requirements in the same mutation function. Instead try to make them reusable.
  • Input Object – Use Mutation argument parameters with validations

The same logic also follows for query, subscription and schema.


We discussed some of the important aspects of GraphQL. Since it is a new technology, developers face roadblocks quite often. The above strategies can be overall used for defining schema, types, query, mutation & subscriptions.

Questions & Comments:

Thank you for reading. If you have got more strategies in any area of GraphQL, share them in the comment section & we will add them in this Best Practice List.

Leave a comment

Your email address will not be published. Required fields are marked *