{"id":352798,"date":"2021-10-01T07:35:02","date_gmt":"2021-10-01T14:35:02","guid":{"rendered":"https:\/\/css-tricks.com\/?p=352798"},"modified":"2021-10-01T07:35:05","modified_gmt":"2021-10-01T14:35:05","slug":"working-with-built-in-graphql-directives","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/working-with-built-in-graphql-directives\/","title":{"rendered":"Working With Built-in GraphQL Directives"},"content":{"rendered":"\n<p><strong>Directives<\/strong> are one of GraphQL\u2019s best \u2014 and most unspoken \u2014 features.<\/p>\n\n\n\n<p>Let&#8217;s explore working with GraphQL\u2019s built-in schema and operation directives that all GraphQL spec compliant APIs must implement. They are extremely useful if you are working with a dynamic front-end because you have the control to reduce the response payload depending on what the user is interacting with.<\/p>\n\n\n\n<!--more-->\n\n\n<h3 class=\"wp-block-heading\" id=\"h-an-overview-of-directives\">An overview of directives<\/h3>\n\n\n<p>Let\u2019s imagine an application where you have the option to customize the columns shown in a table. If you hide two or three columns then there\u2019s really no need to fetch the data for those cells. With GraphQL directives, though, we can choose to include or skip those fields.<\/p>\n\n\n\n<p><a href=\"https:\/\/spec.graphql.org\/draft\/#sec-Language.Directives\" rel=\"noopener\">The GraphQL specification defines what directives are<\/a>, and the location of where they can be used. Specifically, directives can be used by consumer operations (such as a query), and by the underlying schema itself. Or, in simple terms, directives are either based on schema or operation. <dfn><strong>Schema directives<\/strong><\/dfn> are used when the schema is generated, and <dfn><strong>operation directives<\/strong><\/dfn> run when a query is executed.<\/p>\n\n\n\n<p>In short, directives can be used for the purposes of metadata, runtime hints, runtime parsing (like returning dates in a specific format), and extended descriptions (like deprecated).<\/p>\n\n\n<h3 class=\"wp-block-heading\" id=\"h-four-kinds-of-directives\">Four kinds of directives<\/h3>\n\n\n<p>GraphQL boasts four main directives as defined in the <a href=\"https:\/\/spec.graphql.org\/draft\/#sec-Type-System.Directives\" rel=\"noopener\">specification working draft<\/a>, with one of them unreleased as a working draft.<\/p>\n\n\n\n<ul><li><code>@include<\/code><\/li><li><code>@skip<\/code><\/li><li><code>@deprecated<\/code><\/li><li><code>@specifiedBy<\/code> (working draft)<\/li><\/ul>\n\n\n\n<p>If you\u2019re following GraphQL closely, you will also notice two additional directives were merged to the JavaScript implementation that you can try today \u2014 <code>@stream<\/code> and <code>@defer<\/code>. These aren\u2019t part of the official spec just yet while the community tests them in real world applications.<\/p>\n\n\n<h4 class=\"wp-block-heading\" id=\"h-include\"><code>@include<\/code><\/h4>\n\n\n<p>The <code>@include<\/code> directive, true to its name, allows us to conditional include fields by passing an <code>if<\/code> argument. Since it\u2019s conditional, it makes sense to <a href=\"https:\/\/graphql.wtf\/episodes\/8-graphql-variables-with-queries-and-mutations\" rel=\"noopener\">use a variable<\/a> in the query to check for truthiness.<\/p>\n\n\n\n<p>For example, if the variable in the following examples is truthy, then the <code>name<\/code> field will be included in the query response.<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">query getUsers($showName: Boolean) {\n  users {\n    id\n    name @include(if: $showName)\n  }\n}<\/code><\/pre>\n\n\n\n<p>Conversely, we can choose not to include the field by passing the variable <code>$showName<\/code> as <code>false<\/code> along with the query. We can also specify a default value for the <code>$showName<\/code> variable so there\u2019s no need to pass it with every request:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">query getUsers($showName: Boolean = true) {\n  users {\n    id\n    name @include(if: $showName)\n  }\n}<\/code><\/pre>\n\n\n<h4 class=\"wp-block-heading\" id=\"h-skip\"><code>@skip<\/code><\/h4>\n\n\n<p>We can express the same sort of thing with just did, but using <code>@skip<\/code> directive instead. If the value is truthy, then it will, as you might expect, skip that field.<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">query getUsers($hideName: Boolean) {\n  users {\n    id\n    name @skip(if: $hideName)\n  }\n}<\/code><\/pre>\n\n\n\n<p>While this works great for individual fields, there are times we may want to include or skip more than one field. We could duplicate the usage of <code>@include<\/code> and <code>@skip<\/code> across multiple lines like this:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">query getUsers($includeFields: Boolean) {\n  users {\n    id\n    name @include(if: $includeFields)\n    email @include(if: $includeFields)\n    role @include(if: $includeFields)\n  }\n}<\/code><\/pre>\n\n\n\n<p>Both the <code>@skip<\/code> and <code>@include<\/code> directives can be used on fields, fragment spreads, and inline fragments which means we can do something else, like this instead with inline fragments:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"4\"><code markup=\"tt\">query getUsers($excludeFields: Boolean) {\n  users {\n    id\n    ... on User @skip(if: $excludeFields) {\n      name\n      email\n      role\n    }\n  }\n}<\/code><\/pre>\n\n\n\n<p>If a fragment is already defined, we can also use <code>@skip<\/code> and <code>@include<\/code> when we spread a fragment into the query:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"10\"><code markup=\"tt\">fragment User on User {\n  name\n  email\n  role\n}\n\nquery getUsers($excludeFields: Boolean) {\n  users {\n    id\n    ...User @skip(if: $excludeFields)\n  }\n}<\/code><\/pre>\n\n\n<h4 class=\"wp-block-heading\" id=\"h-deprecated\"><code>@deprecated<\/code><\/h4>\n\n\n<p>The <code>@deprecated<\/code> directive appears only in the schema and isn\u2019t something a user would provide as part of a query like we\u2019ve seen above. Instead, the <code>@deprecated<\/code> directive is specified by the developer maintaining the GraphQL API schema.<\/p>\n\n\n\n<p>As a user, if we try to fetch a field that has been deprecated in the schema, we&#8217;ll receive a warning like this that provides contextual help.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" width=\"418\" height=\"372\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/09\/CleanShot-2021-09-23-at-12.39.35@2x.png?resize=418%2C372&#038;ssl=1\" alt=\"A zoomed in example of a syntax-highlighted GraphQL query for getUsers, which contains a users object with id and title properties. The title property is underlined in yellow with a contextual tooltip open below it showing a warning in yellow and white that suggests using the name field instead.\" class=\"wp-image-352800\" srcset=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/09\/CleanShot-2021-09-23-at-12.39.35@2x.png?w=418&amp;ssl=1 418w, https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/09\/CleanShot-2021-09-23-at-12.39.35@2x.png?resize=300%2C267&amp;ssl=1 300w\" sizes=\"(min-width: 735px) 864px, 96vw\" data-recalc-dims=\"1\" \/><figcaption>In this example, the title field has been marked deprecated and the directive provides a helpful hint to replace it.<\/figcaption><\/figure>\n\n\n\n<p>To mark a field deprecated, we need to use the <code>@deprecated<\/code> directive within the schema definition language (SDL), passing a <code>reason<\/code> inside the arguments, like this:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"3\"><code markup=\"tt\">type User {\n  id: ID!\n  title: String @deprecated(reason: \"Use name instead\")\n  name: String!\n  email: String!\n  role: Role\n}<\/code><\/pre>\n\n\n\n<p>If we paired this with the <code>@include<\/code> directive, we could conditionally fetch the deprecated field based on a query variable:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">fragment User on User {\n  title @include(if: $includeDeprecatedFields)\n  name\n  email\n  role\n}\n\nquery getUsers($includeDeprecatedFields: Boolean! = false) {\n  users {\n    id\n    ...User\n  }\n}<\/code><\/pre>\n\n\n<h4 class=\"wp-block-heading\" id=\"h-specifiedby\"><code>@specifiedBy<\/code><\/h4>\n\n\n<p><code>@specifiedBy<\/code> is the fourth of the directives and is currently part of the working draft. It\u2019s set to be used by <a href=\"https:\/\/www.howtographql.com\/graphql-scala\/5-custom-scalars\/\" rel=\"noopener\">custom scalar<\/a> implementations and take a <code>url<\/code> argument that should point to a specification for the scalar.<\/p>\n\n\n\n<p>For example, if we add a <a href=\"https:\/\/graphql.wtf\/episodes\/6-create-a-custom-scalar-type-for-email-address\" rel=\"noopener\">custom scalar for email address<\/a>, we will want to pass the URL to the specification for the regex we use as part of that. Using the last example and the proposal defined in <a href=\"https:\/\/www.w3.org\/Protocols\/rfc822\/\" rel=\"noopener\">RFC #822<\/a>, a scalar for <code>EmailAddress<\/code> would be defined in the schema like so:<\/p>\n\n\n\n<pre rel=\"GraphQL\" class=\"wp-block-csstricks-code-block language-javascript\" data-line=\"\"><code markup=\"tt\">scalar EmailAddress @specifiedBy(url: \"https:\/\/www.w3.org\/Protocols\/rfc822\/\")\n<\/code><\/pre>\n\n\n\n<p>It\u2019s recommended that custom directives have a prefixed name to prevent collisions with other added directives. If  you&#8217;re looking for an example custom directive, and how it&#8217;s created, take a look at <a href=\"https:\/\/github.com\/n1ru4l\/graphql-public-schema-filter\" rel=\"noopener\">GraphQL Public Schema<\/a>. It is a custom GraphQL directive that has both code and schema-first support for annotating which of an API can be consumed in public.<\/p>\n\n\n<h3 class=\"wp-block-heading\" id=\"h-wrapping-up\">Wrapping up<\/h3>\n\n\n<p>So that\u2019s a high-level look at GraphQL directives. Again, I believe directives are a sort of unsung hero that gets overshadowed by other GraphQL features. We already have a lot of control with GraphQL schema, and directives give us even more fine-grained control to get exactly what we want out of queries. That\u2019s the sort of efficiency and that makes the GraphQL API so quick and ultimately more friendly to work with.<\/p>\n\n\n\n<p>And if you\u2019re building a GraphQL API, then be sure to include these directives to the introspection query.. Having them there not only gives developers the benefit of extra control, but an overall better developer experience. Just think how helpful it would be to properly <code>@deprecate<\/code> fields so developers know what to do without ever needing to leave the code? That\u2019s powerful in and of itself.<\/p>\n\n\n\n<hr class=\"wp-block-separator\"\/>\n\n\n\n<p><small>Header graphic courtesy of <a href=\"https:\/\/unsplash.com\/@belgoncalves\" rel=\"nofollow noopener\">Isabel Gon\u00e7alves<\/a> on <a href=\"https:\/\/unsplash.com\/photos\/QSWC7BArVqs\" rel=\"nofollow noopener\">Unsplash<\/a><\/small><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Directives are one of GraphQL\u2019s best \u2014 and most unspoken \u2014 features. Let&#8217;s explore working with GraphQL\u2019s built-in schema and operation directives that all GraphQL spec compliant APIs must implement. They are extremely useful if you are working with a dynamic front-end because you have the control to reduce the response payload depending on what [&hellip;]<\/p>\n","protected":false},"author":285857,"featured_media":352804,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"c2c_always_allow_admin_comments":false,"footnotes":"","jetpack_publicize_message":"Working With Built-in GraphQL Directives by @notrab","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":[]},"categories":[4],"tags":[871],"jetpack_publicize_connections":[],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/09\/graphql-directives-traffic-light.webp?fit=1200%2C600&ssl=1","jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/352798"}],"collection":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/users\/285857"}],"replies":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/comments?post=352798"}],"version-history":[{"count":6,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/352798\/revisions"}],"predecessor-version":[{"id":352891,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/352798\/revisions\/352891"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/media\/352804"}],"wp:attachment":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/media?parent=352798"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/categories?post=352798"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/tags?post=352798"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}