GraphQL Tutorial

Introduction

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

Queries and Mutations

Fields

At its simplest, GraphQL is about asking for specific fields on objects.

Input
{
  lifebank {
	name
  }
}

Output
{
  "data": {
	"lifebank": {
  		"name": "National Blood Bank"
	}
  }
}

This is essential to GraphQL, because you always get back what you expect, and the server knows exactly what fields the client is asking for.

Arguments

Every field and nested object can get its own set of arguments, making GraphQL a complete replacement for making multiple API fetches. You can even pass arguments into scalar fields, to implement data transformations once on the server, instead of on every client separately.

Input
{
  lifebank(email: "[email protected]") {
	telephone
    location	
  }
}

Output
{
  "data": {
	"lifebank": {
  	    "name": "National Blood Bank"
  	    "location": "Costa Rica",
	}
  }
}

GraphQL comes with a default set of types, but a GraphQL server can also declare its own custom types, as long as they can be serialized into your transport format.

Aliases

Aliases allow you to rename the result of a field to whatever you want.

Input
{
  mainLifebank: lifebank(email: "[email protected]") {
	name
  }
  secondaryLifebank: lifebank(email: "[email protected]") {
	name
  }
}

Output
{
  "data": {
	"mainLifebank": {
  		"name": "National Blood Bank"
	},
	"secondaryLifebank": {
  		"name": "National Rescue Blood Bank"
	}
  }
}

Fragments

GraphQL includes reusable units called fragments. Fragments let you construct sets of fields, and then include them in queries where you need to.

Input
{
  leftComparison: lifebank(email: "[email protected]") {
	...comparisonFields
  }
  rightComparison: lifebank(email: "[email protected]") {
	...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  location 
  telephone
}

Output
{
  "data": {
	"leftComparison": {
    	"name": "National Blood Bank",
  	    "location": "Costa Rica",
	    "urgencyLevel": "high" 
	},
	"rightComparison": {
  		"name": "National Rescue Blood Bank",
  	    "location": "Costa Rica",
	    "urgencyLevel": "medium" 
	}
  }
}

The concept of fragments is frequently used to split complicated application data requirements into smaller chunks.

Operation Name

The operation name is a meaningful and explicit name for your operation. It is only required in multi-operation documents, but its use is encouraged because it is very helpful for debugging and server-side logging.

Input
query LifebankNameAndPhotos {
  lifebank{
	name
	photos {
  		url
	}
  }
}

Output
{
  "data": {
	"lifebank": {
  	    "name": "National Blood Bank",
  	    "photos": [
    	    {
      		    "url": "photo1.png"
    	    },
    	    {
      		    "url": "photo2.png"
    	    },
    	    {
      		    "url": "photo3.png"
    	    }
        ]
	}
  }
}

When something goes wrong it is easier to identify a query in your codebase by name instead of trying to decipher the contents.

Variables

GraphQL has a first-class way to factor dynamic values out of the query, and pass them as a separate dictionary. These values are called variables.

When we start working with variables, we need to do three things:

Replace the static value in the query with $variableName.
Declare $variableName as one of the variables accepted by the query.
Pass variableName: value in the separate, transport-specific (usually JSON) variables dictionary.

Variables
{
  "email": "[email protected]"
}

Input
query LifebankNameAndPhotos($email: Lifebank) {
  lifebank(email: $email) {
	name
	photos {
  		url
	}
  }
}

Output
{
  "data": {
	"lifebank": {
  	    "name": "National Blood Bank",
  	    "photos": [
    	    {
      		    "url": "photo1.png"
    	    },
    	    {
      	    	"url": "photo2.png"
    	    },
    	    {
      	    	"url": "photo3.png"
        	}
        ]
	}
  }
}

Directives

A directive can be attached to a field or fragment inclusion, and can affect execution of the query in any way the server desires. The core GraphQL specification includes exactly two directives, which must be supported by any spec-compliant GraphQL server implementation:

@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.

Variables
{
    "email": "[email protected]",
	"withPhotos": false
}

Input
query Lifebank($email: Lifebank, $withPhotos: Boolean!) {
  lifebank(name: $email) {
	name
	photos @include(if: $withPhotos) {
  		url
	}
  }
}

Output
{
  "data": {
	"lifebank": {
  	"name": "National Blood Bank" 
   }
}

Mutations

Any query could be implemented to cause a data write. However, it is useful to establish a convention that any operation that causes writes must be explicitly sent through a mutation.

Variables
{
  "email": "[email protected]",
  "urgencyLevel": "high"
}

Input
mutation ChangeUrgencyLevel($ep: Episode!, $review: ReviewInput!) {
  updateUrgencyLevel(email: $email, urgencyLevel: $urgencyLevel) {
	urgencyLevel
  }
}

Output
{
  "data": {
	"updateUrgencyLevel": {
  	"urgencyLevel": "high",
	}
  }
}

Similar to queries, if the mutation field returns an object type, you can request nested fields. This can be useful to get the new state of an object after an update.

Inline Fragments

If you are querying a field that returns an interface or a union type, you will need to use inline fragments to access data on the underlying concrete type.

Variables
{
  "ep": "JEDI"
}

Input
query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
	name
	... on Droid {
  	primaryFunction
	}
	... on Human {
  	height
	}
  }
}

Output
{
  "data": {
	"hero": {
  	"name": "R2-D2",
  	"primaryFunction": "Astromech"
	}
  }
}

Schema and Types

Type System

Every GraphQL service defines a set of types which completely describe the set of possible data you can query on that service. Then, when queries come in, they are validated and executed against that schema.

Input
{
  lifebank {
	name
	email
  }
}

Output
{
  "data": {
	"lifebank ": {
  	“name": "National Blood Bank",
  	"email": "[email protected]"
	}
  }
}

Type Language

GraphQL services can be written in any language. The "GraphQL schema language" - it's similar to the query language, and allows us to talk about GraphQL schemas in a language-agnostic way.

Object Types and Fields

The most basic components of a GraphQL schema are object types. In the GraphQL schema language, we might represent it like this:

Input
type Character {
 name: String!
 appearsIn: [Episode!]!
}

Character is a GraphQL Object Type, meaning it's a type with some fields. Most of the types in your schema will be object types.
name and appearsIn are fields on the Character type. That means that name and appearsIn are the only fields that can appear in any part of a GraphQL query that operates on the ‘Character’ type.
String is one of the built-in scalar types - these are types that resolve to a single scalar object, and can't have sub-selections in the query.
[Episode!]! represents an array of Episode objects. Since it is also non-nullable, you can always expect an array (with zero or more items) when you query the ‘appearsIn’ field.

Arguments

Every field on a GraphQL object type can have zero or more arguments. All arguments in GraphQL are passed by name specifically, can be either required or optional. When an argument is optional, we can define a default value - if the unit argument is not passed, it will be set to METER by default.

Input
type Starship {
 id: ID!
 name: String!
 length(unit: LengthUnit = METER): Float
}

The Query and Mutation Types

Every GraphQL service has a query type and may or may not have a mutation type. These types are the same as a regular object type, but they are special because they define the entry point of every GraphQL query.

Schema
schema {
 query: Query
 mutation: Mutation
}

Input
query {
  hero {
	name
  }
  droid(id: "2000") {
	name
  }
}

Output
{
  "data": {
	"hero": {
  		"name": "R2-D2"
	},
	"droid": {
  		"name": "C-3PO"
	}
  }
}

Mutations work in a similar way - you define fields on the Mutation type, and those are available as the root mutation fields you can call in your query.

Scalar Types

Scalar types represent the leaves of the query. We know this because those fields don't have any sub-fields - they are the leaves of the query.

Input
{
  hero {
	name
	appearsIn
  }
}

Output
{
  "data": {
	"hero": {
  	   "name": "R2-D2",
  	   "appearsIn": [
    	   "NEWHOPE",
    	   "EMPIRE",
    	   "JEDI"
  	    ]
	}
  }
}

GraphQL comes with a set of default 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.
Boolean: true or false.
ID: The ID scalar type represents a unique identifier The ID type is serialized in the same way as a String.

Enumeration Types

Also called Enums, enumeration types are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to:

Validate that any arguments of this type are one of the allowed values.
Communicate through the type system that a field will always be one of a finite set of values.

Enum
enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

Lists and Non-Null

The Non-Null type modifier be used when defining arguments for a field, which will cause the GraphQL server to return a validation error if a null value is passed as that argument, whether in the GraphQL string or in the variables.

Lists work in a similar way: We can use a type modifier to mark a type as a List, which indicates that this field will return an array of that type.

The Non-Null and List modifiers can be combined.

Type
type Character {
  name: String!
  appearsIn: [Episode]!
}

Variables
{
  "id": null
}

Input
query DroidById($id: ID!) {
  droid(id: $id) {
	name
  }
}

Output
{
  "errors": [
    {
  	   "message": "Variable \"$id\" of non-null type \"ID!\" must not be null.",
  	   "locations": [
    	{
      	  "line": 1,
      	  "column": 17
    	}
  	]
	}
  ]
}

Interfaces

An Interface is an abstract type that includes a certain set of fields that a type must include to implement the interface.

Interface
interface Character {
  id: ID!
  name: String!
  friends: [Character]
  appearsIn: [Episode]!
}

Example 1
type Human implements Character {
  id: ID!
  name: String!
  friends: [Character]
  appearsIn: [Episode]!
  starships: [Starship]
  totalCredits: Int
}

Example 2
type Droid implements Character {
  id: ID!
  name: String!
  friends: [Character]
  appearsIn: [Episode]!
  primaryFunction: String
}

Interfaces are useful when you want to return an object or set of objects.

Union Types

Union types are very similar to interfaces, but they don't get to specify any common fields between the types.

Union
union SearchResult = Human | Droid | Starship

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

	... on Droid {
  	    name
  	    primaryFunction
	}

	... on Starship {
  	    name
        length
	}
  }
}

Output
{
  "data": {
	"search": [
  	{
    	"__typename": "Human",
    	"name": "Han Solo",
    	"height": 1.8
  	},
  	{
    	"__typename": "Human",
    	"name": "Leia Organa",
    	"height": 1.5
  	},
  	{
    	"__typename": "Starship",
    	"name": "TIE Advanced x1",
    	"length": 9.2
  	}
	]
  }
}

Input Types

In the GraphQL schema language, input types look exactly the same as regular object types, but with the keyword input instead of type.

Input Type
input ReviewInput {
 stars: Int!
 commentary: String
}

Variables
{
  "ep": "JEDI",
  "review": {
	"stars": 5,
	"commentary": "This is a great movie!"
  }
}

Input
mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
	stars
	commentary
  }
}

Output
{
  "data": {
	"createReview": {
  	"stars": 5,
  	"commentary": "This is a great movie!"
	}
  }
}

The fields on an input object type can themselves refer to input object types, but you can't mix input and output types in your schema. Input object types also can't have arguments on their fields.

Execution

After being validated, a GraphQL query is executed by a GraphQL server which returns a result that mirrors the shape of the requested query, typically as JSON.

Type System
type Query {
    human(id: ID!): Human
}

type Human {
    name: String
    appearsIn: [Episode]
    starships: [Starship]
}

enum Episode {
    NEWHOPE
    EMPIRE
    JEDI
}

type Starship {
    name: String
}

Input
{
  human(id: 1002) {
	name
	appearsIn
	starships {
    	name
	}
  }
}

Output
{
  "data": {
	"human": {
  	    "name": "Han Solo",
  	    "appearsIn": [
    	    "NEWHOPE",
    	    "EMPIRE",
    	    "JEDI"
  	    ],
  	    "starships": [
    	{
      	    "name": "Millenium Falcon"
    	},
    	{
        	"name": "Imperial shuttle"
    	}
  	    ]
	}
  }
}

Each field on each type is backed by a function called the resolver which is provided by the GraphQL server developer. When a field is executed, the corresponding resolver is called to produce the next value.

Language Support

Top 5

JavaScript

Serve

GraphQL.js: The reference implementation of the GraphQL specification, designed for running GraphQL in a Node.js environment.
Apollo Server: A set of GraphQL server packages from Apollo that work with various Node.js HTTP frameworks (Express, Connect, Hapi, Koa etc).

Client

Apollo Client: A powerful JavaScript GraphQL client, designed to work well with React, React Native, Angular 2, or just plain JavaScript.
GraphQL Request: A simple and flexible JavaScript GraphQL client that works in all JavaScript environments (the browser, Node.js, and React Native) - basically a lightweight wrapper around fetch.

Tools

GraphiQL: An interactive in-browser GraphQL IDE.
GraphQL CLI: A command line tool for common GraphQL development workflows.

Services

Apollo: A cloud service for monitoring the performance and usage of your GraphQL backend.
Hasura: Hasura connects to your databases and microservices and instantly gives you a production-ready GraphQL API.
Postman: An HTTP Client that supports editing GraphQL queries.

GraphQL Tutorial

Introduction

Queries and Mutations

Fields

Arguments

Aliases

Fragments

Operation Name

Variables

Directives

Mutations

Inline Fragments

Schema and Types

Type System

Type Language

Object Types and Fields

Arguments

The Query and Mutation Types

Scalar Types

Enumeration Types

Lists and Non-Null

Interfaces

Union Types

Input Types

Execution

Language Support

Top 5

JavaScript

Serve

Client

Tools

Services

Sistemas Edenia

Community

More

Introduction​

Queries and Mutations​

Fields​

Arguments​

Aliases​

Fragments​

Operation Name​

Variables​

Directives​

Mutations​

Inline Fragments​

Schema and Types​

Type System​

Type Language​

Object Types and Fields​

Arguments​

The Query and Mutation Types​

Scalar Types​

Enumeration Types​

Lists and Non-Null​

Interfaces​

Union Types​

Input Types​

Execution​

Language Support​

Top 5​

JavaScript​

Serve​

Client​

Tools​

Services​

Sistemas Edenia

Community

More

Introduction

Queries and Mutations

Fields

Arguments

Aliases

Fragments

Operation Name

Variables

Directives

Mutations

Inline Fragments

Schema and Types

Type System

Type Language

Object Types and Fields

Arguments

The Query and Mutation Types

Scalar Types

Enumeration Types

Lists and Non-Null

Interfaces

Union Types

Input Types

Execution

Language Support

Top 5

JavaScript

Serve

Client

Tools

Services