Enhance customer experiences with Apollo GraphOS


<p><em>This is a guest post by&nbsp;</em><a href="https://github.com/confuser/" target="_blank" rel="noreferrer noopener"><em>James Mortemore</em></a><em>, who is a software engineer at&nbsp;</em><a href="https://www.yld.io/" target="_blank" rel="noreferrer noopener"><em>YLD</em></a><em>. He has an extensive background in API development &amp; enterprise integration architecture.</em></p>



<p>Out of the box, GraphQL supports validating your inputs based on type information. For example, you can ensure that an argument is a particular scalar type, such as String or Int. You can also enforce the shape of object arguments using input object types. While this prevents a large class of possible errors, this doesn’t cater to more complex validation needs like enforcing the length of a string, or the size of a number.</p>



<h3 class="wp-block-heading" id="7716"><a href="#a-simple-example-user-sign-up-form" aria-hidden="true" class="aal_anchor" id="a-simple-example-user-sign-up-form"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A simple example: User sign up form</h3>



<p>To see how schema validation could be used, it’s easiest to start with an example. The SDL&nbsp;<a rel="noreferrer noopener" href="https://github.com/facebook/graphql/pull/90" target="_blank">(Schema Definition Language)</a>&nbsp;will be as follows:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type SignUpInput {
  email: String!
  password: String!
  firstName: String!
  lastName: String!
}

type Mutation {
  signUp(input: SignUpInput!)
}</code></pre>



<p>The above enforces all fields are strings, and ensures they are not null. However, we’ve got some additional constraints that come from the database that we need to be wary of. In our server, the backend database is using a&nbsp;<code>VARCHAR(255)</code>&nbsp;field for all Strings. This means providing a field greater than 255 characters will cause an error!</p>



<p>Today, people most commonly write this kind of validation logic in their resolver functions or models. However, this means we can’t easily see our validation logic, and we have to write some repetitive code to verify the same kinds of conditions over and over.</p>



<h3 class="wp-block-heading" id="cf07"><a href="#a-new-option-validation-with-schema-directives" aria-hidden="true" class="aal_anchor" id="a-new-option-validation-with-schema-directives"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A new option: Validation with schema directives</h3>



<p>It’s possible to add this logic directly to your SDL using a new module:&nbsp;<a href="https://www.npmjs.com/package/graphql-constraint-directive" target="_blank" rel="noreferrer noopener">graphql-constraint-directive</a>. This module exposes a&nbsp;<code>@constraint</code>&nbsp;directive to decorate an SDL with validation rules.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="500" height="355" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/0_UvAXIh0HW_97IpYt.jpg" alt="" class="wp-image-756" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/0_UvAXIh0HW_97IpYt.jpg 500w, https://wp.apollographql.com/wp-content/uploads/2020/03/0_UvAXIh0HW_97IpYt-300x213.jpg 300w" sizes="auto, (max-width: 500px) 100vw, 500px" /></figure>



<p>Thanks to&nbsp;<a href="https://www.npmjs.com/package/graphql-tools" target="_blank" rel="noreferrer noopener">graphql-tools</a>&nbsp;and&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/" target="_blank" rel="noreferrer noopener">apollo-server</a>, it’s easy to integrate them. Here’s how you do it:</p>



<pre class="wp-block-preformatted">npm install graphql-constraint-directive</pre>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { makeExecutableSchema } = require(&#039;graphql-tools&#039;)
const ConstraintDirective = require(&#039;graphql-constraint-directive&#039;)

const typeDefs = `SDL HERE`
const schema = makeExecutableSchema({
  typeDefs, schemaDirectives: { constraint: ConstraintDirective }
})</code></pre>



<p>After just a few lines of configuration, it’s now possible to decorate any part of your SDL with&nbsp;<code>@constraint</code>&nbsp;to attach validation rules. A full example can be found on the&nbsp;<a href="https://github.com/confuser/graphql-constraint-directive/blob/master/README.md" target="_blank" rel="noreferrer noopener">graphql-constraint-directive readme</a>.</p>



<p>Here’s how your SDL will look like with some constraint directives added in:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type SignUpInput {
  email: String! @constraint(format: &quot;email&quot;, maxLength: 255)
  password: String! @constraint(maxLength: 255)
  firstName: String! @constraint(pattern: &quot;^[0-9a-zA-Z]*$&quot;, maxLength: 255)
  lastName: String! @constraint(pattern: &quot;^[0-9a-zA-Z]*$&quot;, maxLength: 255)
}

type Mutation {
  signUp(input: SignUpInput!)
}</code></pre>



<p>Before we move on, it’s good to mention that this isn’t a silver bullet solution. More complex validation rules, such as those which rely on state (e.g. does this entity exist?) will need to remain elsewhere in your code.</p>



<h3 class="wp-block-heading" id="f7b1"><a href="#looking-at-the-example-in-detail" aria-hidden="true" class="aal_anchor" id="looking-at-the-example-in-detail"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Looking at the example in detail</h3>



<p>Let’s break down the example above, field by field…</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">email: String! @constraint(format: &quot;email&quot;, maxLength: 255)</code></pre>



<p><code>@constraint</code>&nbsp;has a number of available arguments (check the&nbsp;<a href="https://github.com/confuser/graphql-constraint-directive/blob/master/README.md" target="_blank" rel="noreferrer noopener">readme</a>&nbsp;for a full list) depending on the field type. In this case, as it&#8217;s a string, the option of defining a&nbsp;<code>format</code>&nbsp;can be used. This particular constraint is validating that the value is an email address and it&#8217;s 255 characters at most.</p>



<p>Another way to write this could be to split it into multiple&nbsp;<code>@constraint</code>&nbsp;directives. Note that directives are resolved right to left. For example, maxLength would be resolved before format in the following field definition:&nbsp;<code>email: String! @constraint(format: &quot;email&quot;) @constraint(maxLength: 255)</code></p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">lastName: String! @constraint(pattern: &quot;^[0-9a-zA-Z]*$&quot;, maxLength: 255)</code></pre>



<p>On a different field, it is confirming the last name is a maximum of 255 characters and also matches a regular expression. In this instance, alphanumeric only (sorry double barrelled surnames!).</p>



<p>You could remove&nbsp;<code>maxLength</code>&nbsp;and perform this check within the expression. However, regex and&nbsp;<code>.length</code>&nbsp;return unexpected results when&nbsp;<a href="https://blog.jonnew.com/posts/poo-dot-length-equals-two" target="_blank" rel="noreferrer noopener">emojis are used&#8230; 💩</a></p>



<h3 class="wp-block-heading" id="4b2f"><a href="#receiving-validation-errors-on-the-client" aria-hidden="true" class="aal_anchor" id="receiving-validation-errors-on-the-client"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Receiving validation errors on the client</h3>



<p>When a consumer sends a request which breaks these rules, the application will respond with an error message.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
	&quot;errors&quot;: [{
		&quot;message&quot;: &quot;Variable \&quot;$input\&quot; got invalid value {\&quot;email\&quot;:\&quot;foo💩\&quot;}; Expected type ConstraintString at value.email; Must be in email format&quot;
	}]
}</code></pre>



<p>Note that isn’t a very user-friendly message. If you wish to provide your own message, you can do that within the&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/api/apollo-server#formaterror" target="_blank" rel="noreferrer noopener">formatError</a>&nbsp;option to Apollo Server.</p>



<h2 class="wp-block-heading" id="5d66"><a href="#how-does-the-constraint-directive-work" aria-hidden="true" class="aal_anchor" id="how-does-the-constraint-directive-work"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How does the @constraint directive work?</h2>



<p>There’s something interesting about the error message above! Specifically, it says&nbsp;<code>Expected type ConstraintString</code>, even though the field is defined as&nbsp;<code>String!</code>. The constraint directive wraps each field with its own&nbsp;<a href="https://github.com/confuser/graphql-constraint-directive/blob/e553a0526725edf015ae4dea16ff6f380500c25e/scalars/string.js#L6" target="_blank" rel="noreferrer noopener">scalar</a>&nbsp;<a href="https://github.com/confuser/graphql-constraint-directive/blob/e553a0526725edf015ae4dea16ff6f380500c25e/scalars/number.js#L4" target="_blank" rel="noreferrer noopener">type</a>.&nbsp;<code>&lt;a href=&quot;https://github.com/apollographql/graphql-tools&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql-tools&lt;/a&gt;</code>&nbsp;takes care of this implementation detail for the consumer, so the fields in question can still just be the type&nbsp;<code>String!</code>&nbsp;when submitting the mutation.&nbsp;<code>ConstraintString</code>&nbsp;&amp;&nbsp;<code>ConstraintNumber</code>&nbsp;will never appear within your Schema Definition Language (SDL), and the client/consumer needn&#8217;t be concerned by it.</p>



<p>When the value of each decorated field is parsed, the validation rules are executed. For example, here’s the code for&nbsp;<code>minLength</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">if (args.minLength &amp;&amp; !isLength(value, { min: args.minLength })) {
          throw new GraphQLError(`Must be at least ${args.minLength} characters in length`)
}</code></pre>



<p>If all validation rules pass,&nbsp;<code>ConstraintString</code>/<code>ConstraintNumber</code>&nbsp;executes the original scalar&#8217;s&nbsp;<code>parseValue</code>&nbsp;and returns it. This allows wrapped scalars to execute their own parseValue function, enabling support for custom scalar types!</p>



<p>Using this approach, it’s trivial to <a href="https://www.apollographql.com/docs/apollo-server/schema/directives/#custom-directives" target="_blank" rel="noreferrer noopener">create your own custom directives</a> to validate and manipulate field values. You can look at the code of <a rel="noreferrer noopener" href="https://github.com/confuser/graphql-constraint-directive" target="_blank">graphql-constraint-directive</a> as an example! To publish a custom directive as a module, ensure the custom directive class is exported as the <code>main</code> module entry.</p>



<p>I hope this inspires you to develop and publish your own custom directives!</p>


Backend

GraphQL validation using directives

Backend

GraphQL validation using directives

Stay in our orbit