You might have heard about Hasura, the new technology that lets you quickly create GraphQL APIs to access data in your databases. Here's a quick tutorial that will help you understand why technologies like GraphQL and Hasura are so important for API development.

For an example of where you might use Hasura, imagine we're building an app to store comments in a Postgres database. In our application, we need to be able to do two things:

But how exactly do we communicate with the database from a frontend application?

That's where Hasura comes into play. It will generate GraphQL APIs from a database. That way, from the frontend, we will communicate with Hasura through GraphQL, and beneath, Hasura will handle accessing the database.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL comes with important advantages:

GraphQL has emerged as an alternative to REST APIs for client-server communication requirements. Which one you choose depends much on your objectives and the specific needs of your app.

. The body of the request is a stringified JSON object that contains a 

// POST request body
{
  query: `
    query GetUser($id: ID!) {
      id
      name
    }
  `,
  variables: { id: 1 }
}

 is a request written in GraphQL language, and 

 stores values that we can use in the request.

The core part of a GraphQL server is a GraphQL schema. It describes the data available to the client applications. For example, for a GraphQL server created on top of a database with single table 

type Query {
  users: [User]
}

type User {
  // all the fields from table `users`:
  id: ID
  name: String
  age: Int
}

The schema tells us what types we can expect for particular fields. Hence we know that the returned 

To get data from a GraphQL service, we use a 

. We construct it by specifying the root type, e.g. 

, and all the fields we want from the type. For example, the server exposes fields 

 type. But maybe we don't need all of them? One of the core concepts of GraphQL is the "take what you want" approach. We can ask for exactly what we need.

query GetUserIds {
  users {
    id
  }
}

When it doesn't have any parameters, the query doesn't need a name:

This is a request that the client application would send:

POST
body:
{
  "query": "{ users { id } }"
}

We can also pass variables. Let's say we want to fetch a particular user based on the user 

POST
body:
{
  "query": "query GetUser($id: ID!) { 
  users(id: $id) { id, name } }",
  "variables": {
    "id": 1
  }
}

. These let us update one or more objects. Take a look at the following example:

mutation CreateUser(
  $name: String, $age: Int) {
  createUser(
    name: $name, age: $age) {
    id
  }
}

 of a newly created user. What does it mean? It means that mutations can not only be used to modify underlying resources, but we also get results back.

Sometimes, your application needs real-time data. For example, you're building a chat application and need to display up-to-date message updates.

With GraphQL, we can subscribe to real-time data from a server, using 

. They have the same format as queries, with the only difference being a 

subscription GetUserIds {
  users {
    id
  }
}

The subscription API is exposed over WebSockets, so we need to hit a WebSocket URL from a client. It means that instead of sending requests to the server on 

As we mentioned before, sending GraphQL requests is no more than sending POST requests over HTTP to an endpoint. For this reason, on the client, we can use built-in browser APIs.

However, the GraphQL ecosystem now has multiple clients, including: 

Clients like these provide cache support, subscriptions support, and much more. When building bigger apps, you'll want to use a GraphQL client.

GraphQL is a very convenient way to work with JSON data. It can be used with any language or framework. It's not tied to any specific database, and on top of that, it has an excellent ecosystem and a huge community.

We gain a lot of flexibility by using GraphQL. Instead of waiting for a new endpoint whenever we need to fetch a different set of data, we can handle it independently by writing an adequate query based on our specification. We also don't have to send multiple endpoints to fetch the information - we can handle it in one GraphQL query.

Congratulations - you just learned the basics of GraphQL. It's a lot of new knowledge, but don't worry - we'll play a bit with queries and mutations in follow up lessons on the topics of GraphQL as well as Hasura.

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">An Introduction to Hasura and GraphQL</h1><p>You might have heard about Hasura, the new technology that lets you quickly create GraphQL APIs to access data in your databases. Here's a quick tutorial that will help you understand why technologies like GraphQL and Hasura are so important for API development.</p><h2 class="heading-anchor-text" id="hasura-and-graphql-in-practice"><span>Hasura and GraphQL in Practice</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#hasura-and-graphql-in-practice">#</a></h2><p>For an example of where you might use Hasura, imagine we're building an app to store comments in a Postgres database. In our application, we need to be able to do two things:</p><ol><li><p>Add new comments - insert new entries into the database.</p></li><li><p>Display the comments in the UI - extract them from the database.</p></li></ol><p>But how exactly do we communicate with the database from a frontend application?</p><p>That's where Hasura comes into play. It will generate GraphQL APIs from a database. That way, from the frontend, we will communicate with Hasura through GraphQL, and beneath, Hasura will handle accessing the database.</p><h2 class="heading-anchor-text" id="what-is-graphql?"><span>What is GraphQL?</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#what-is-graphql?">#</a></h2><p>GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL comes with important advantages:</p><ul><li><p>provides a complete and understandable description of the data in your API</p></li><li><p>gives clients the power to ask for exactly what they need and nothing more</p></li><li><p>makes it easier to evolve APIs over time </p></li><li><p>enables powerful developer tools</p></li></ul><p>GraphQL has emerged as an alternative to REST APIs for client-server communication requirements. Which one you choose depends much on your objectives and the specific needs of your app.</p><h2 class="heading-anchor-text" id="moving-to-graphql"><span>Moving to GraphQL</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#moving-to-graphql">#</a></h2><p>A GraphQL server exposes <strong>one endpoint</strong> and accepts <strong>POST requests</strong>. The body of the request is a stringified JSON object that contains a <code>query</code>, along with <code>variables</code>. Here's an example:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-b-A6izkaiBXe0Wr99ZGAG" id="cm-b-A6izkaiBXe0Wr99ZGAG">// POST request body
{
  query: `
    query GetUser($id: ID!) {
      id
      name
    }
  `,
  variables: { id: 1 }
}</textarea><p>Here, <code>query</code> is a request written in GraphQL language, and <code>variables</code> stores values that we can use in the request.</p><p>But let's take it bit by bit.</p><h2 class="heading-anchor-text" id="graphql-schema"><span>GraphQL Schema</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#graphql-schema">#</a></h2><p>The core part of a GraphQL server is a GraphQL schema. It describes the data available to the client applications. For example, for a GraphQL server created on top of a database with single table <code>users</code>, the schema could look like this:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-l3zKaf7q_ey7AQIwZq-6G" id="cm-l3zKaf7q_ey7AQIwZq-6G">type Query {
  users: [User]
}

type User {
  // all the fields from table `users`:
  id: ID
  name: String
  age: Int
}</textarea><p>The schema tells us what types we can expect for particular fields. Hence we know that the returned <code>name</code>, for example, will always be a <code>String</code>.</p><h2 class="heading-anchor-text" id="graphql-query-basics"><span>GraphQL Query Basics</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#graphql-query-basics">#</a></h2><p>To get data from a GraphQL service, we use a <strong>query</strong>. We construct it by specifying the root type, e.g. <code>User</code>, and all the fields we want from the type. For example, the server exposes fields <code>id</code>, <code>name</code>, and <code>age</code> for the <code>User</code> type. But maybe we don't need all of them? One of the core concepts of GraphQL is the "take what you want" approach. We can ask for exactly what we need.</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-TMO_mesGdyG_KBQle9e5j" id="cm-TMO_mesGdyG_KBQle9e5j">query GetUserIds {
  users {
    id
  }
}</textarea><p>When it doesn't have any parameters, the query doesn't need a name:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-mxTRv04MMT9kapM34c9lf" id="cm-mxTRv04MMT9kapM34c9lf">query {
  users {
    id
  }
}</textarea><p>Or we can skip <code>query</code>. This still is valid GraphQL syntax:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-yZwF-dGxdrli-5_4cxPB1" id="cm-yZwF-dGxdrli-5_4cxPB1">{
  users {
    id
  }
}</textarea><p>This is a request that the client application would send:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-wzyCEHQerinBe6VVxrGuH" id="cm-wzyCEHQerinBe6VVxrGuH">POST
body:
{
  "query": "{ users { id } }"
}</textarea><p>We can also pass variables. Let's say we want to fetch a particular user based on the user <code>id</code>:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-3nvintsq6mPIrwXIP97HX" id="cm-3nvintsq6mPIrwXIP97HX">POST
body:
{
  "query": "query GetUser($id: ID!) { 
  users(id: $id) { id, name } }",
  "variables": {
    "id": 1
  }
}</textarea><h2 class="heading-anchor-text" id="graphql-mutations"><span>GraphQL Mutations</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#graphql-mutations">#</a></h2><p>For modifying data, GraphQL provides us <strong>mutations</strong>. These let us update one or more objects. Take a look at the following example:</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-xds8FFDORRsC0h_Lrr7pZ" id="cm-xds8FFDORRsC0h_Lrr7pZ">mutation CreateUser(
  $name: String, $age: Int) {
  createUser(
    name: $name, age: $age) {
    id
  }
}</textarea><p>We pass dynamic values for a new user's <code>name</code> and <code>age</code>, and we also return the <code>id</code> of a newly created user. What does it mean? It means that mutations can not only be used to modify underlying resources, but we also get results back.</p><h2 class="heading-anchor-text" id="graphql-subscriptions"><span>GraphQL Subscriptions</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#graphql-subscriptions">#</a></h2><p>Sometimes, your application needs real-time data. For example, you're building a chat application and need to display up-to-date message updates.</p><p>With GraphQL, we can subscribe to real-time data from a server, using <strong>subscriptions</strong>. They have the same format as queries, with the only difference being a <code>subscription</code> keyword instead of <code>query</code>.</p><textarea data-iscodemirror="true" class="d-none" data-mode="text/javascript" data-uniqueid="cm-6cB6o8K63nS-oRzt5H2Ok" id="cm-6cB6o8K63nS-oRzt5H2Ok">subscription GetUserIds {
  users {
    id
  }
}</textarea><p>The subscription API is exposed over WebSockets, so we need to hit a WebSocket URL from a client. It means that instead of sending requests to the server on <code>https://your-server.app/graphql</code>, we use the WebSocket protocol: <code>ws://your-server.app/graphql</code>.</p><h2 class="heading-anchor-text" id="client-libraries"><span>Client Libraries</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#client-libraries">#</a></h2><p>As we mentioned before, sending GraphQL requests is no more than sending POST requests over HTTP to an endpoint. For this reason, on the client, we can use built-in browser APIs.</p><p>However, the GraphQL ecosystem now has multiple clients, including: </p><ul><li><p><a href="https://www.apollographql.com/docs/react" rel="noopener noreferrer nofollow">Apollo Client</a></p></li><li><p><a href="https://relay.dev/" rel="noopener noreferrer nofollow">Relay</a></p></li><li><p><a href="https://formidable.com/open-source/urql/docs/" rel="noopener noreferrer nofollow">urql</a></p></li></ul><p>Clients like these provide cache support, subscriptions support, and much more. When building bigger apps, you'll want to use a GraphQL client.</p><h2 class="heading-anchor-text" id="why-choose-graphql?"><span>Why Choose GraphQL?</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#why-choose-graphql?">#</a></h2><p>GraphQL is a very convenient way to work with JSON data. It can be used with any language or framework. It's not tied to any specific database, and on top of that, it has an excellent ecosystem and a huge community.</p><p>We gain a lot of flexibility by using GraphQL. Instead of waiting for a new endpoint whenever we need to fetch a different set of data, we can handle it independently by writing an adequate query based on our specification. We also don't have to send multiple endpoints to fetch the information - we can handle it in one GraphQL query.</p><h2 class="heading-anchor-text" id="where-to-next-with-graphql-and-hasura"><span>Where to Next With GraphQL and Hasura</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#where-to-next-with-graphql-and-hasura">#</a></h2><p>Congratulations - you just learned the basics of GraphQL. It's a lot of new knowledge, but don't worry - we'll play a bit with queries and mutations in follow up lessons on the topics of GraphQL as well as Hasura.</p><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

An Introduction to Hasura and GraphQL

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript