Categories
GraphQL JavaScript

An Introduction to GraphQL

GraphQL is a query language for our API and a server-side runtime for running queries by using a type system for our data.

In this article, we’ll look at how to make basic queries to a GraphQL API.

Defining the API

We define an API by defining the types and fields for those types and provide functions for each field on each type.

For example, if we have the following type:

type Query {  
  person: Person  
}

Then we have to create a function for the corresponding type to return the data:

function Query_person(request) {  
  return request.person;  
}

Making Queries

Once we have a GraphQL service running, we can send GraphQL queries to validate and execute on the server.

For example, we can make a query as follows:

{  
  person {  
    firstName  
  }  
}

Then we may get JSON like the following:

{  
  "person": {  
    "firstName": "Joe"  
  }  
}

Queries and Mutations

Queries are for getting data from the GraphQL server and mutations are used for manipulating data stored on the server.

For example, the following is a query to get a person’s name:

{  
  person {  
    name  
  }  
}

Then we may get the following JSON from the server:

{  
  "data": {  
    "person": {  
      "name": "Joe"  
    }  
  }  
}

The field name returns a String type.

We can change the query as we wish if we want to get more data. For example, if we write the following query:

{  
  person {  
    name  
    friends {  
      name  
    }  
  }  
}

Then we may get something like the following as a response:

{  
  "data": {  
    "person": {  
      "name": "Joe",  
      "friends": [  
        {  
          "name": "Jane"  
        },  
        {  
          "name": "John"  
        }  
      ]  
    }  
  }  
}

The example above has friends being an array. They look the same from the query perspectively, but the server knows what to return based on the type specified.

Arguments

We can pass in arguments to queries and mutations. We can do a lot more with queries if we pass in arguments to it.

For example, we can pass in an argument as follows:

{  
  person(id: "1000") {  
    name      
  }  
}

Then we get something like:

{  
  "data": {  
    "person": {  
      "name": "Luke"  
    }  
  }  
}

from the server.

With GraphQL, we can pass in arguments to nested objects. For example, we can write:

{  
  person(id: "1000") {  
    name  
    height(unit: METER)  
  }  
}

Then we may get the following response:

{  
  "data": {  
    "person": {  
      "name": "Luke",  
      "height": 1.9  
    }  
  }  
}

In the example, the height field has a unit which is an enum type that represents a finite set of values.

unit may either be METER or FOOT.

Fragments

We can define fragments to let us reuse complex queries.

For example, we can define a fragment and use it as follows:

{  
  leftComparison: person(episode: FOO) {  
    ...comparisonFields  
  }  
  rightComparison: person(episode: BAR) {  
    ...comparisonFields  
  }  
}  
​  
fragment comparisonFields on Character {  
  name  
  appearsIn  
  friends {  
    name  
  }  
}

In the code above, we defined the comparisonFields fragment which has the list of fields we want to include in each query.

Then we have the leftComparison and rightComparison queries which include the fields of the comparisonFields fragment by using the ... operator.

Then we get something like:

{  
  "data": {  
    "leftComparison": {  
      "name": "Luke",  
      "appearsIn": [  
        "FOO",  
        "BAR"  
      ],  
      "friends": [  
        {  
          "name": "Jane"  
        },  
        {  
          "name": "John"  
        }  
      ]  
    },  
    "rightComparison": {  
      "name": "Mary",  
      "appearsIn": [  
        "FOO",  
        "BAR"  
      ],  
      "friends": [  
        {  
          "name": "Mary"  
        },  
        {  
          "name": "Alex"  
        }  
      ]  
    }  
  }  
}

Using variables inside fragments

We can pass in variables into fragments as follows:

query PersonComparison($first: Int = 3){  
  leftComparison: person(episode: FOO) {  
    ...comparisonFields  
  }  
  rightComparison: person(episode: BAR) {  
    ...comparisonFields  
  }  
}  
​  
fragment comparisonFields on Character {  
  name  
  appearsIn  
  friends(first: $first) {  
    name  
  }  
}

Then we may get something like:

{  
  "data": {  
    "leftComparison": {  
      "name": "Luke",  
      "appearsIn": [  
        "FOO",  
        "BAR"  
      ],  
      "friends": [  
        {  
          "name": "Jane"  
        },  
        {  
          "name": "John"  
        }  
      ]  
    },  
    "rightComparison": {  
      "name": "Mary",  
      "appearsIn": [  
        "FOO",  
        "BAR"  
      ],  
      "friends": [  
        {  
          "name": "Mary"  
        },  
        {  
          "name": "Alex"  
        }  
      ]  
    }  
  }  
}

as a response.

The operation type may either be a query, mutation, or subscription and describes what operator we’re intending to do. It’s required unless we’re using the query shorthand syntax. In that case, we can’t supply a name or variable definition for our operation.

The operation name is a meaningful and explicit name for our operation. It’s required in multi-operation documents. But its use is encouraged because it’s helpful for debugging and server-side logging.

It’s easy to identify the operation with a name.

Conclusion

GraphQL is a query language that lets us send requests to a server in a clear way. It works by sending nested objects with operation type and name along with any variables to the server.

Then the server will return us the response that we’re looking for.

Operation types include queries for getting data and mutations for making changes to data on the server.

Categories
GraphQL JavaScript

Introduction to GraphQL — Variables and Complex Operations

GraphQL is a query language for our API and a server-side runtime for running queries by using a type system for our data.

In this article, we’ll look at more complex GraphQL operations, including passing in variables, directives, mutations, and more.

Variables

In most apps, the arguments for queries need to be dynamic. It wouldn’t be a good idea to pass in dynamic arguments directly to the query string.

Fortunately, GraphQL lets us pass in variables into our operations request.

For example, we can write:

query PersonName($id: Int) {  
  person(id: $id) {  
    name  
  }  
}

to pass in an $id variable into our person query.

Then we can pass in variables via an object to make the request:

{  
  "id": 1000  
}

Then we get something like:

{  
  "data": {  
    "person": {  
      "name": "Jane"  
    }  
  }  
}

as the response.

Variable definitions

Variable definitions start with the variable name prefixed with a $, then the type of the variable.

In the example above, we have $id as the variable name and Int as the type.

All declared variables must be either a scalar, enums or other input object types.

If we want to pass a complex object into a field, we need to know the input type to match on the server.

Default variables

We can set default values for variables as follows:

query PersonName($id: Int = 1) {  
  person(id: $id) {  
    name  
  }  
}

In the code above, we added = 1 after $id: Int to set the default value for $id to 1.

Directives

We can use directives to dynamically change the structure and shape of our queries using variables.

For example, we can include directives as follows to make our query dynamic:

query Person($id: Int, $withFriends: Boolean!) {  
  person(id: $id) {  
    name  
    friends @include(if: $withFriends) {  
      name  
    }  
  }  
}

In the code above, we have the @include(if: $withFriends) directive to conditionally includes friends if $withFriends is true.

Therefore, if we make the following query with the following variables:

{  
  "id": 1000,  
  "withFriends": false  
}

Then we may get something like:

{  
  "data": {  
    "person": {  
      "name": "Jane"  
    }  
  }  
}

as a response.

A directive can be attached to a field or fragment inclusion and can affect the execution of the query in any way the server desires.

The core GraphQL specification includes 2 directives that must be supported by any spec-compliant GraphQL server implementation:

  • @include(if: Boolean) — only include this field if the argument if true.
  • @skip(if: Boolean) — skip this field if the argument is true.

It helps us get out of situations where we would have to do string manipulating to add and remove fields in our query.

Mutations

We can use mutations to send requests to change data on the server.

They’re similar to queries, except that it starts with the keyword mutation instead.

For example, we can define a mutation as follows:

mutation CreatePerson($firstName: String, $lastName: String) {  
  createPerson(firstName: $firstName, lastName: $lastName) {  
    firstName  
    lastName  
  }  
}

Then if we make the following query:

{  
  "firstName": "Joe",  
  "lastName": "Smith"  
}

we may get the following response:

{  
  "data": {  
    "createPerson": {  
      "firstName": "Joe",  
      "lastName": "Smith"  
    }  
  }  
}

In the response, we return the firstName and lastName fields as we specified in the request.

A mutation can contain multiple fields like a query. Mutations fields run in series.

This means that if we sent 2 createPerson mutations in one request. The first will finish before the second begins.

Inline Fragments

We can define interface and union types with GraphQL requests.

To do this, we use inline fragments to access data on the underlying concrete type.

For example, we can write the following query:

query Thing($id: Int!) {  
  person(id: $id) {  
    name  
    ... on Person{  
      gender  
    }  
    ... on Robot{  
      memory  
    }  
  }  
}

In the query above, the ...on operator indicates that we include an inline fragment within our query, where Person and Robot are our fragments.

Named fragments can also be inline fragments since they have a type attached.

Meta fields

We can request a __typename field to get the type of data returned in the response.

For example, if we have the following query:

{  
  search(text: "an") {  
    __typename  
    ... on Human {  
      name  
    }  
    ... on Robot {  
      name  
    }  
  }  
}

Then we may get the following response from the server:

{  
  "data": {  
    "search": [  
      {  
        "__typename": "Human",  
        "name": "Hans"  
      },  
      {  
        "__typename": "Robot",  
        "name": "Jane"  
      }  
    ]  
  }  
}

Conclusion

We can define mutations to make requests to change data.

To make requests dynamic, we can use variables to include variable data and directives for conditional inclusion of data in our response.

We can also use inline fragments for union types and include the type of data returned in the response by including the __typename property.

Categories
GraphQL JavaScript

Introduction to GraphQL Schemas and Types

GraphQL is a query language for our API and a server-side runtime for running queries by using a type system for our data.

In this article, we’ll look at the GraphQL type system and how it describes what data can be queried.

Schemas and Types

GraphQL requests are about selecting fields on objects.

In a query, we have a root object, then we select a field from that and fields below that level if it exists all the way to the bottom level.

For example, if we have the query:

{  
  person {  
    name  
  }  
}

Then we get something like:

{  
  "data": {  
    "person": {  
      "name": "Jane"  
    }  
  }  
}

as the response.

A GraphQL query closely matches the result so we can predict what the query will return without knowing that much about the serve.

But it’s still useful to have an exact description of data we can ask for.

This is where explicit types are useful.

Type language

GraphQL services can be written in any language. Therefore, types have to be defined in a language-agnostic way.

Object types and fields

We can define a GraphQL data type as follows:

type Person {  
  name: String!  
  addresses: [Address!]!  
}

In the code above, we created a new type with the type keyword. In the type, we have the name field, which is String , and addresses , which is an array of Address es, which is another type.

String is a built-in scalar type. The exclamation marks mean the field is not nullable. Therefore, String! is a non-nullable string.

[Address!]! is an array of Address objects. It’s also non-nullable, so we can always expect an array with zero or more items when we query for addresses . Since Address! is also non-nullable, we can always expect every item of the array to be an Address object.

Arguments

Every field of a GraphQL object type can have zero or more arguments.

For example, we can write the following:

type Person {  
  name: String!  
  height(unit: HeightUnit = METER): Float  
}

In the code above, we have the height field in the Person that takes a unit as the argument. unit is of type HeightUnit which is set to METER by default.

height returns a Float.

The Query and Mutation types

There’re 2 types that are special within a schema. They’re Query and Mutation .

Every GraphQL service has a query type and may or may not have an mutation type.

These types are the same as any other object type, but they’re special because they define the entry point of every GraphQL query.

If we have a query like the following:

query {  
  person {  
    name  
  }  
  robot(id: "2000") {  
    name  
  }  
}

Then the GraphQL service needs to have the query type with the person and robot fields:

type Query {  
  person(name: String): Person  
  robot(id: ID!): Robot  
}

We define mutation types the same way. We define fields on the Mutation type and those are available as the root mutation fields we can call in our query.

Scalar types

Scalar fields are what all object types contain in the end. They’re the most basic types of fields.

GraphQL comes with the following scalar types out of the box:

  • Int — a signed 32-bit integer
  • Float — a signed double-precision floating-point value
  • String — a UTF-8 character sequence
  • Booleantrue or false
  • ID — a unique identifier that used for fetching an object or as the key for a cache. It’s serialized the same way as a String but it’s not intended to be human-readable

Most GraphQL service implementations also let us specify custom scalar types.

We can define one as follows:

scalar Date

Then it’s up to use to decide how to serialize, deserialize and validate them.

Enumeration types

Enum types are special types of scalar that are restricted to a particular set of allowed values.

It lets us validate that any argument of the type is one of the allowed values.

Also, it communicates through the type system that a field will always be one of a finite set of values.

We can define an enum as follows:

enum Fruit {  
  APPLE  
  ORANGE  
  GRAPE  
}

Then if we have Fruit , we expect it to be either APPLE, ORANGE or GRAPE .

Conclusion

We can define types so that we can validate the data that’s submitted to the GraphQL server.

To do this, we create a type with the type keyword if it’s an object type.

We can also create scalar types which are the most basic types that can be included in other types or referenced directly. We can define them with the scalar keyword.

To define a type with fixed values, we can define an enum type with a few possible constant values.

The exclamation mark indicates that a type is not nullable.

Categories
GraphQL JavaScript

Creating a Basic GraphQL Server with Express

We can create a simple GraphQL server with Express. To do this, we need the express-graphql and graphql packages.

In this article, we’ll look at how to create a simple GraphQL server with express and make a simple schema for it.

Create an Express GraphQL Server

First, we have to install the packages by running:

npm install express express-graphql graphql --save

Then we can create a server.js file in our project directory and add the following code:

const express = require('express');  
const graphqlHTTP = require('express-graphql');  
const { buildSchema } = require('graphql');
const schema = buildSchema(`  
  type Query {  
    hello: String  
  }  
`);

const root = {  
  hello: () => {  
    return 'Hello world!';  
  },  
};

const app = express();
app.use('/graphql', graphqlHTTP({  
  schema: schema,  
  rootValue: root,  
  graphiql: true,  
}));
app.listen(3000, () => console.log('server started'));

In the code above, we created our express instance, which then we added the schema to it, which we defined by writing:

const schema = buildSchema(`  
  type Query {  
    hello: String  
  }  
`);

With this schema, we’re allowed to submit the hello query to our GraphQL server.

Then we have our root object, which is our resolver for resolving the hello query:

const root = {  
  hello: () => {  
    return 'Hello world!';  
  },  
};

We just return the 'Hello world!' string to the user who queries our server.

The code graphiql: true means that enabled the GraphiQL tool so that we can go to localhost:3000/graphql to see the GraphiQL tool. This is where we can type in our query.

Note that we don’t need a special client to make requests to our client. We can make a POST request to the /graphql endpoint without our GraphQL request payload to send the request to our server.

For example, if we use Postman by typing in our /graphql endpoint and then pass in {“query”: “{ hello }”} as the request payload string. In the header, we set Content/Type to application/json , then we get:

{  
    "data": {  
        "hello": "Hello world!"  
    }  
}

as the response.

We can also make the request in JavaScript with the Fetch API as follows:

(async () => {  
  const response = await fetch(  
    "/graphql",  
    {  
      method: "POST",  
      headers: {  
        "Content-Type": "application/json",  
        Accept: "application/json"  
      },  
      body: JSON.stringify({ query: "{ hello }" })  
    }  
  );  
  const data = await response.json();  
  console.log(data);  
})();

Then we get:

{  
  "data": {  
    "hello": "Hello world!"  
  }  
}

In many cases, we would need to accept arguments in our resolver and query.

To do this, we can write the following:

const express = require('express');  
const graphqlHTTP = require('express-graphql');  
const { buildSchema } = require('graphql');  
const schema = buildSchema(`  
  type Query {  
    rollDice(numSides: Int): Int  
  }  
`);

const root = {  
  rollDice: (params) => {  
    const { numSides } = params;  
    return Math.ceil(Math.random() * numSides);  
  },  
};

const app = express();
app.use('/graphql', graphqlHTTP({  
  schema: schema,  
  rootValue: root,  
  graphiql: true,  
}));
app.listen(3000, () => console.log('server started'));

In the code above, we have the root object with the rollDice resolver function which as the params parameter to get the arguments that are passed into GraphQL request.

Then we return a random number from it and return it. The number will be returned within the response.

To make our rollDice resolver accept the request, we included:

type Query {  
  rollDice(numSides: Int): Int  
}

in our schema so that it’ll take in the numSides argument.

If we go to the /graphq page in our browser, and then type in:

{  
  rollDice(numSides: 10)  
}

in the left pane, we’ll get a number between 0 and 10.

To make a GraphQL POST request that takes in arguments, we can write the following:

(async () => {  
  const numSides = 6;  
  const query = `query RollDice($numSides: Int) {  
   rollDice(numSides: $numSides)  
  }`; 

  const response = await fetch(  
    "/graphql",  
    {  
      method: "POST",  
      headers: {  
        "Content-Type": "application/json",  
        Accept: "application/json"  
      },  
      body: JSON.stringify({  
        query,  
        variables: { numSides },  
      })  
    });  
  const data = await response.json();  
  console.log(data);  
})();

In the code above, we have the query , which is:

query RollDice($numSides: Int) {  
  rollDice(numSides: $numSides)  
}

and variables , which is:

variables: { numSides }

The JSON body that we sent with the request is:

{  
  "query": "query RollDice($numSides: Int) {  
     rollDice(numSides: $numSides)  
  }",  
  "variables": {  
    "numSides": 6  
  }  
}

This is the same what we ran in the GraphiQL UI, but needed the query RollDice to wrap our query so that we can pass in the numSides variable.

Conclusion

We can easily create a GraphQL Server with Express by using the express-graphql package.

After that, we have to create our resolver function and schema to let us accept GraphQL requests.

Resolvers can also accept variables. In there, we return the result, which will then be returned in the response to the user.

To test our API, we can use the GraphiQL GUI to enter queries and test them.

Categories
GraphQL JavaScript

Create and Use Data Types with Express GraphQL

We can create a simple GraphQL server with Express. To do this, we need the express-graphql and graphql packages.

In this article, we’ll look at how to create and use our own GraphQL data types.

Object Types

In many cases, we don’t want to accept and return a number or a string from the API. We can create our own data types to accept and return whatever we want from the API.

With the express-graphql package, we can define our data types in a string and then pass it into the buildSchema function.

For example, we can write the following code to define our types, build a schema, and add our resolvers to our code:

const express = require('express');  
const graphqlHTTP = require('express-graphql');  
const { buildSchema } = require('graphql');  
const schema = buildSchema(`  
  type RandomDie {  
    numSides: Int!  
    rollOnce: Int!  
    roll(numRolls: Int!): [Int]  
  } type Query {  
    getDie(numSides: Int): RandomDie  
  }  
`);

class RandomDie {  
  constructor(numSides) {  
    this.numSides = numSides;  
  } 

  rollOnce() {  
    return 1 + Math.floor(Math.random() * this.numSides);  
  } 

  roll({ numRolls }) {  
    const output = [];  
    for (let i = 0; i < numRolls; i++) {  
      output.push(this.rollOnce());  
    }  
    return output;  
  }  
}

const root = {  
  getDie: ({ numSides }) => {      
    return new RandomDie(numSides || 6);  
  },  
};

const app = express();app.use('/graphql', graphqlHTTP({  
  schema: schema,  
  rootValue: root,  
  graphiql: true,  
}));  
app.listen(3000, () => console.log('server started'));

In the code above, we defined our schema by writing:

const schema = buildSchema(`  
  type RandomDie {  
    numSides: Int!  
    rollOnce: Int!  
    roll(numRolls: Int!): [Int]  
  }  
  type Query {  
    getDie(numSides: Int): RandomDie  
  }  
`);

We defined the RandomDie type with the numSides field and rollOnce and roll methods.

Then we defined our getDie query to let access the members that we defined in the RandomDie type.

Then we defined our RandomDie class, which we’ll use in our getDie resolver which we’ll define later:

class RandomDie {  
  constructor(numSides) {  
    this.numSides = numSides;  
  }  
  rollOnce() {  
    return 1 + Math.floor(Math.random() * this.numSides);  
  }  
  roll({ numRolls }) {  
    const output = [];  
    for (let i = 0; i < numRolls; i++) {  
      output.push(this.rollOnce());  
    }  
    return output;  
  }  
}

In the class, we created the rollOnce and roll methods where we’ll return the results.

Then finally, we define our getDie resolver as follows:

const root = {  
  getDie: ({ numSides }) => {      
    return new RandomDie(numSides || 6);  
  },  
};

We get numSides from the parameter and then passed it into the RandomDie constructor when we instantiate it.

Then in the /graphql page, we can make the following query in the GraphiQL UI:

{  
  getDie(numSides: 6) {  
    rollOnce  
    roll(numRolls: 3)  
    numSides  
  }  
}

and we should get something like the following as a response:

{  
  "data": {  
    "getDie": {  
      "rollOnce": 3,  
      "roll": [  
        6,  
        4,  
        5  
      ],  
      "numSides": 6  
    }  
  }  
}

Note that we access fields and call methods with no arguments the same way, as we did with rollOnce and numSides .

This way of defining objects provides us with some advantages over traditional REST APIs. Instead of using an API request to get basic information about an object and multiple requests to find out more about the object, we can just make one query to get the things we need.

This saves bandwidth, increases performance, and simplifies client-side logic.

Conclusion

We can create new types by putting it in the string with other parts of the schema. Then we can use the buildSchema function to build the schema.

Once we did that, we create a class to map the type fields into class members. Then we can instantiate that class in our resolver.

Then finally, we can make our request by sending the class name as the query name and then the member names with arguments if required inside the braces.