GraphQL Directives

GraphQL queries are a powerful way to declare data in your application.

query myAwesomeQuery($keyword: String) {
  description,
  title
}

After getting some experience writing these queries you’ll want to start doing more advanced things: inclusion/exclusion of fields, schema decorators, deferring fields etc.

Today we are going to talk about Directives. Directives provide a way describe additional options to the GraphQL executor. Essentially a directive allows the GraphQL to change the result of our queries based on criteria we provide. Today, the GraphQL spec defines two standard directives: @skip and @include.

@skip

The skip directive, when used on fields or fragments, allows us to exclude fields based on some condition.

query myAwesomeQuery($isAwesome: Boolean) {
  awesomeField @skip(if: $isAwesome)
}

This example will return awesomeField only if $isAwesome is false.

@include

The include directive, allows us to include fields based on some condition.

query myAwesomeQuery($isAwesome: Boolean) {
  awesomeField @include(if: $isAwesome)
}

This example will return awesomeField only if $isAwesome is true.

Pretty neat right?

Let’s see what’s inside these directives

So before we get into it, directives aren’t really something GraphQL authors want you to create. Check out this github discussion: here.

We’ve determined that user-supplied custom directives is a non-goal for graphql-js at this time. — Lee Byron

If you’re interested in seeing a custom directive built, checkout this great blog post by Clay Allsopp here.

Let’s take a look how @skip is implemented. The root of a GraphQL directive is a GraphQLDirective class. Essentially this class is instantiated with the appropriate metadata.

Okay we have this directive, now how does it get used? GraphQL, graphql-js to be exact, employs a function called shouldIncudeNode. This function determines if a field should be included based on either the @include and @skip directives.

Note. @skip always has higher precedence than @include.

In GraphQL, a selectionSet is the set of information we are trying to resolve from our server. First, the GraphQL parses the string and turns it into an abstract syntax tree. Then after passing Validation, the selectionSet is executed and this is where our shouldIncudeNode function is called.

If you want to see how this is implemented check it out here!

Also, if you want to see how GraphQL queries work from query to execution check this blog from Jonas Helfer here.

Conclusion

GraphQL is super cool. At a glance all these concepts seem super new and I’m sure JavaScript developers are already feeling this as fatigue! But really, all you need to do is take a deep breath, dive into source code, and you’ll see that GraphQL is a powerful tool that is easy to use. If it was complex, it wouldn’t be such a good developer experience right?

Also, if you wanna jumpstart your usage of GraphQL today. Checkout the Apollo Stack. If you’re using REST APIs and hating your life, checkout how our client interface works here.

Ciao.