• Hierarchical - queries look exactly like the data they return.
• Client-specified queries - the client has the liberty to dictate what to fetch from the server,
• Strongly typed - you can validate a query syntactically and within the GraphQL type system before execution. This also helps leverage powerful tools that improve the development experience, such as GraphiQL.
• Introspective - you can query the type system using the GraphQL syntax itself. This is great for parsing incoming data into strongly-typed interfaces, and not having to deal with parsing and manually transforming JSON into objects.

npm i graphql express express-graphql -S   #Install required packages

var express = require('express');
var graphqlHTTP = require('express-graphql');
var { buildSchema } = require('graphql');

// Initialize a GraphQL schema
var schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// Root resolver
var root = { 
  hello: () => 'Hello world!'
};

// Create an express server and a GraphQL endpoint
var app = express();
app.use('/graphql', graphqlHTTP({
  schema: schema,  // Must be provided
  rootValue: root,
  graphiql: true,  // Enable GraphiQL when server endpoint is accessed in browser
}));
app.listen(4000, () => console.log('Now browse to localhost:4000/graphql'));

Schema

type User {
  id: ID!
  name: String!
  age: Int
}

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

Constructing Types

var schema = buildSchema(`
  type Query {
    user(id: Int!): Person
    users(gender: String): [Person]
  },
  type Person {
    id: Int
    name: String
    age: Int
    gender: String  
  }
`);

Resolver

...
var users = [  // Dummy data
  {
    id: 1,
    name: 'Brian',
    age: '21',
    gender: 'M'
  },
  {
    id:2,
    name: 'Kim',
    age: '22',
    gender: 'M'
  },
  {
    id:3,
    name: 'Joseph',
    age: '23',
    gender: 'M'
  },
  {
    id:3,
    name: 'Faith',
    age: '23',
    gender: 'F'
  },
  {
    id:5,
    name: 'Joy',
    age: '25',
    gender: 'F'
  }
];

var getUser = function(args) { ... }  // Return a single user
var retrieveUsers = function(args) { ... } // Return  a list of users
...
var root = { 
  user: getUser,   // Resolver function to return user with specific id
  users: retrieveUsers
};

...
var getUser = function(args) { // return a single user based on id
  var userID = args.id;
  return users.filter(user => {
    return user.id == userID;
  })[0];
}

var retrieveUsers = function(args) { // Return a list of users. Takes an optional gender parameter
  if(args.gender) {
    var gender = args.gender;
    return users.filter(user => user.gender === gender);
  } else {
    return users;
  }
}
...

query getSingleUser {
    user {
        name
        age
        gender
    }
}

When something goes wrong either in your network logs or your GraphQL server, it is easier to identify a query in your codebase by name instead of trying to decipher the contents.

query getSingleUser($userID: Int!) {
    user(id: $userID) {
        name
        age
        gender
    }
}

{ 
    "userID":1
}

Aliases

query getUsersWithAliasesError($userAID: Int!, $userBID: Int!) {
    user(id: $userAID) {
        name
        age
        gender
    },
    user(id: $userBID) {
        name
        age
        gender
    }
}

{ 
    "userAID":1,
    "userBID":2
}

query getUsersWithAliases($userAID: Int!, $userBID: Int!) {
    userA: user(id: $userAID) {
        name
        age
        gender
    },
    userB: user(id: $userBID) {
        name
        age
        gender
    }
}

{ 
    "userAID":1,
    "userBID":2
}

Fragments

query getUsersWithFragments($userAID: Int!, $userBID: Int!) {
    userA: user(id: $userAID) {
        ...userFields
    },
    userB: user(id: $userBID) {
        ...userFields
    }
}

fragment userFields on Person {
  name
  age
  gender
}

{ 
    "userAID":1,
    "userBID":2
}

Directives

• @include(if: Boolean) Only include this field in the result if the argument is true.
• @skip(if: Boolean) Skip this field if the argument is true.

query getUsers($gender: String, $age: Boolean!, $id: Boolean!) {
  users(gender: $gender){
    ...userFields
  }
}

fragment userFields on Person {
  name
  age @skip(if: $age)
  id @include(if: $id)
}

{
  "gender": "F",
  "age": true,
  "id": true
}

Mutations

// Add mutations
var schema = buildSchema(`
  ...
  type Mutation {
    updateUser(id: Int!, name: String!, age: String): Person
  }
`);
...
var updateUser = function({id, name, age}) {  // Update a user and return new user details
  users.map(user => {
    if(user.id === id) {
      user.name = name;
      user.age = age;
      return user;
    }
  });
  return users.filter(user=> user.id === id) [0];
}
...

var root = { 
  user: getUser,
  users: retrieveUsers,
  updateUser: updateUser  // Include mutation function in root resolver
};

mutation updateUser($id: Int!, $name: String!, $age: String) {
  updateUser(id: $id, name:$name, age: $age){
    ...userFields
  }
}

fragment userFields on Person {
  name
  age
  gender
}

{
  "id": 1,
  "name": "Keavin",
  "age": "27"
}

Resources

• Introduction to GraphQL
• Learning GraphQL