GraphQL API’s are gaining popularity and are among the most popular types of web services available today. They use the GraphQL magic to allow numerous clients, including browser apps, to communicate with a server which can further be resolved to talk to different data sources. As a result, it’s critical to properly build APIs to avoid complications down the future. We will go over two out of many useful things GraphQL provides us out of the box to help us better design our API.

GraphQL Directives

A directive in a GraphQL request is a mechanism to give the GraphQL server more information about a GraphQL document’s execution and type validation behavior.

A directive is any string in GraphQL document that begins with the @ character. Every GraphQL schema has three built-in directive :

1. @include
2. @skip
3. @deprecated

Let’s talk about them one by one.

@include

@include directive can be used after fields to provide a condition. That condition controls whether the field (or fragment) should be included in the response. The syntax for using this directive looks like this :

feildName @include(if: $someTest)

Example : We want to include the author of an event only when showAuthor is true

@skip

This directive is simply the reverse of the include directive. We provide a condition which decides whether the field (or fragment) should be excluded in the response.

Syntax:

fieldName @skip(if: $someTest)

Example: We skip author if partial parameter is set to true

@deprecated

This special directive can be used in GraphQL servers to indicate deprecated portions of a GraphQL service’s schema such as deprecated fields. It supports a ‘reason’ argument to provide the reason behind deprecation

Example :

Note that you can have a field followed by multiple directives. You can also repeat include multiple times or use both skip and include. None of them have precedence over the other.

GraphQL Fragments :

When constructing something complex, one useful method is to divide it into smaller components and then concentrate on one at a time. The smaller parts should ideally be built in such a way that they are not coupled with each other and are also reusable. Communication between these small pieces and their integration will result in the creation of the larger system.

In GraphQL, fragments are the composition units of language. They allow you to divide large GraphQL actions into smaller chunks. It’s simply reusable piece of GraphQL operations.

Defining a fragment

The Events part of the definition is called the ‘type condition’ of the fragment. You can only define fragments on object types. You cannot define fragment on scalar value.

Using the fragment

To use the fragment , you spread (fragment spread) its name where the fields were originally used in the query.

Without Fragment :

With Fragment (using fragment we defined earlier) :

We can also make use of fragments to reduce duplication in GraphQL document.

Above, you can see we are using identical structure for ‘ownedLaptops’ and ‘ownedDesktops’. We can use fragment here so that we define these fields just once and use that fragment where the fields are repeated.

Now we can use above defined fragment to improve our query.

Epic ! Hopefully you understood how to use these GraphQL features and they will help you design your API’s better. Happy Coding 🌸

More resources :
1. How to design better APIs — Ronald Blüthl
2. GraphQL fragments
3. GraphQL directives