<p><a href="https://graphql.org/">GraphQL</a> is a query language for APIs and a runtime for fulfilling those queries with your existing data, developed by Facebook in 2012 and open sourced in 2015. The goal was to create a query language that allowed fine-grained control over the needed data a client can request to an API server.</p>
<p>A GraphQL service is created by defining <strong>types</strong> and <strong>fields</strong> to those types in a <strong>schema</strong>. A commom way to defining the schema of your GraphQL service is through the GraphQL Schema Definition Language (SDL).</p>
<p>In this article, I&#39;ll show how to create a GraphQL schema compliant with the <a href="https://relay.dev/docs/guides/graphql-server-specification/">Relay GraphQL Server</a> specification.</p>
<h2>Defining your schema in GraphQL</h2>
<p>A GraphQL schema should informe the users about all the types and objects that can be queried and mutated on the graph. GraphQL even provides a feature to query metadata about those types and objects, which can be used to document the GraphQL.</p>
<p>Let&#39;s define a simple schema using GraphQL SDL (Schema Definition Language):</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">&quot;&quot;&quot;
Serialize and validate JavaScript dates.
&quot;&quot;&quot;
scalar Date

&quot;&quot;&quot;
Node interface
&quot;&quot;&quot;
interface Node {
  id: ID!
}

&quot;&quot;&quot;
Priority level
&quot;&quot;&quot;
enum Priority {
  LOW
  MEDIUM
  HIGH
}

&quot;&quot;&quot;
A task that the user should complete
&quot;&quot;&quot;
type Task implements Node {
  &quot;Task ID&quot;
  id ID! # ID is a GraphQL special type for IDs.
  &quot;Task title&quot;
  title String!
  &quot;Task creation date&quot;
  created: Date!
  &quot;Task modification date&quot;
  modified: Date
  priority: Priority!
}

&quot;&quot;&quot;
Needed input data to add a new task.
&quot;&quot;&quot;
input AddTaskInput {
  title: String!
  priority: Priority
}

type Query {
  &quot;Get a task by ID&quot;
  task(id: ID!): Task
}

type Mutation {
  addTask(input: AddTaskInput): Task
}</div>
</code></pre><ol>
<li>First we define a <a href="https://graphql.org/learn/schema/#scalar-types">custom Date scalar</a> that should validate and serialize Date objects;</li>
<li>We define a <code>Node</code> interface. I&#39;ll explain more on why I&#39;m defining this interface the next topic;</li>
<li>We define an <a href="https://graphql.org/learn/schema/#enumeration-types">enumeration type</a> to define the valid priority status of a task;</li>
<li>We create our <code>Task</code> type with all the field it should contain. Notice that all field with the exclamation mark at the end are obligatory;</li>
<li>We add an input called <code>AddTaskInput</code> that defines the obligatory data to add a new <code>Task</code>;</li>
<li>In the Query type (which is a GraphQL reserved type), we define what queries are available from our root object;</li>
<li>In the Mutation type (which is a GraphQL reserved type), we define which operations to alter our data are available. Such operations are called <a href="https://graphql.org/learn/queries/#mutations">mutations</a>.</li>
</ol>
<p>Notice that, in GraphQL, comments between quotes serve as documentation (it&#39;ll be parsed and displayed in your GraphiQL web documentation interface), while the comments that start with <code>#</code> are ignored.</p>
<h2>Querying your data in GraphQL</h2>
<p>Tipically, you&#39;d query a GraphQL server like this:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">{
  task(id: &quot;2&quot;) {
    title
  }
}</div>
</code></pre><p>Which would return the following, in JSON format:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: {
      &quot;title&quot;: &quot;Write GraphQL tutorial&quot;
    }
  }
}</div>
</code></pre><p>In the query above, we started with a special &quot;root&quot; object, from where we select the <code>task</code> field with the id equals to <code>2</code> Then, we select the <code>title</code> field from the <code>task</code> object. But, if no task has an id equals to 2? In this case, our response would be:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: null
  }
}</div>
</code></pre><p>Or, in case of a error, we would receive this response:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: null
  },
  &quot;errors&quot;: [
    {
      &quot;message&quot;: &quot;Internal server error.&quot;
    }
  ]
}</div>
</code></pre><p>You may want rename a field before using your data. Well, you can create your <a href="https://graphql.org/learn/queries/#aliases">aliases</a> just like this:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">{
  todo: task(id: &quot;2&quot;) {
    name: title
  }
}</div>
</code></pre><p>And that would be the return:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;todo&quot;: {
      &quot;name&quot;: &quot;Write GraphQL tutorial&quot;
    }
  }
}</div>
</code></pre><p>GraphQL also provides the feature of create <a href="https://graphql.org/learn/queries/#fragments">query fragments</a> and setting up  <a href="https://graphql.org/learn/queries/#directives">directives</a> to query your data. I&#39;ll need to add more complexity to our current schema in order to explain that, so, for while, let&#39;s move to the next topic.</p>
<h2>The Relay GraphQL Server specification</h2>
<p>Despite you may not want to use <a href="https://relay.dev/">Relay</a> (or even React) to consume your GraphQL data, their specification is very useful and provides a common ground of what developers should expect from a GraphQL server.</p>
<p>Remember that <code>Node</code> interface we defined above? Its purpose is to provide a <a href="https://graphql.org/learn/global-object-identification/">global object identification</a> for all the GraphQL nodes in our server. Therefore, a GraphQL client can handle re-fetching and caching in a more standardized way. Notice that each ID must be globally unique on your application.</p>
<p>As the <code>Node</code> interface will be used for all objects in our server, GraphQL provides a reusable unit called <a href="https://graphql.org/learn/queries/#fragments">fragment</a>. Now, let&#39;s add a new way the query nodes on our schema:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql"># ...

type Query {
  &quot;Get a node by ID&quot;
  node(id: ID!): Node
}

# ...</div>
</code></pre><p>Notice that the <code>task</code> query was removed, as it is no more needed. And now, we will re-do our query using a fragment:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql"># We name the query and pass a variable
# to improve the development experience.
query getTask(id: ID!) {
  node(id: $id) {
    ...taskFields
  }
}

fragment taskFields on Task {
  title
}</div>
</code></pre><p>And now, we will change our schema to comply with the Relay GraphQL Server specification. Take some time to read the comments in order to understand what is being done here.</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">&quot;&quot;&quot;
Serialize and validate JavaScript dates.
&quot;&quot;&quot;
scalar Date

&quot;&quot;&quot;
Node interface
&quot;&quot;&quot;
interface Node {
  id: ID!
}

&quot;&quot;&quot;
Priority level
&quot;&quot;&quot;
enum Priority {
  LOW
  MEDIUM
  HIGH
}

&quot;&quot;&quot;
A task that the user should complete
&quot;&quot;&quot;
type Task implements Node {
  &quot;Task ID&quot;
  id ID! # ID is a GraphQL special type for IDs.
  &quot;Task title&quot;
  title String!
  &quot;Task creation date&quot;
  created: Date!
  &quot;Task modification date&quot;
  modified: Date
  priority: Priority!
}

&quot;&quot;&quot;
Define an edge of the task,
containing a node and a pagination cursor.
&quot;&quot;&quot;
type TaskEdge {
  cursor: String!
  node: Task
}

&quot;&quot;&quot;
Define a connection between the
task edges, including the PageInfo
object for pagination info.
&quot;&quot;&quot;
type TaskConnection {
  edges: [TaskEdge] # Yes, we use brackets to define arrays in GraphQL
  pageInfo: PageInfo!
}

&quot;&quot;&quot;
Provides pagination info
for a cursor-based pagination
&quot;&quot;&quot;
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

&quot;&quot;&quot;
Needed input data to add a new task.
&quot;&quot;&quot;
input AddTaskInput {
  title: String!
  priority: Priority
}

type Query {
  node(id: ID!): Node
  tasks(
    first: Int, # The amount of tasks requested
    after: String # Cursor to mark the point
  ): TaskConnection
}

type Mutation {
  addTask(input: AddTaskInput): Task
}</div>
</code></pre><p>At this point, the metaphor of <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graphs</a> used here should be very clear. Each <strong>edge</strong> of your graph has a node and a <strong>connection</strong> of edges has a collection of nodes that can be paginated. Note that, in this specification, is expected that you implement a <a href="https://www.prisma.io/docs/concepts/components/prisma-client/pagination#cursor-based-pagination">cursor based pagination</a>, rather than a <a href="https://www.prisma.io/docs/concepts/components/prisma-client/pagination#offset-pagination">offset pagination</a> (follow the previous link to have more information about their differences.</p>
<p>And that&#39;s all we need to comply with the <a href="https://relay.dev/docs/guides/graphql-server-specification/">Relay GraphQL Server Specification</a>.</p>
<p>In the next article, I&#39;ll implement a GraphQL server using all the concepts that we learned here.</p>
<p>Source:</p>
<p><a href="https://graphql.org/">GraphQL</a></p>


Douglas Moura

Douglas Moura

#graphql

Introduction to GraphQL