GraphQL Essentials

Section 1

Introduction

GraphQL is a language-independent specification for client-server communication. Its declarative query language enables application clients to specify which back-end data to fetch, without worrying about how that data is populated. A GraphQL server receives queries from clients and fulfils them by populating requested fields with back-end data from arbitrarily many sources (such as relational databases and REST APIs).

Section 2

The Evolution of GraphQL

In 2012, Facebook’s native mobile apps for iOS and Android were thin wrappers around the views of their mobile website. These apps often crashed when making multiple simultaneous REST API calls. To resolve this issue, Facebook overhauled their infrastructure to enable their apps to fetch multiple types of data with a single API call. This solution paved the way for the GraphQL specification, which Facebook first released publicly in 2015. Today, GraphQL powers almost all of Facebook’s data fetching and is used in production by organizations such as IBM, Walmart, Netflix, The New York Times, Intuit, GitHub, and Airbnb.

Benefits of GraphQL

Benefit	Description
Suitable for complex systems and microservices	GraphQL unifies multiple systems behind a single API, thus masking the complexity of those systems from clients.
Data fetching with a single API call	GraphQL is typically served over HTTP via a single endpoint that expresses the full set of a platform’s capabilities.
Autogenerating API documentation	A GraphQL API is tightly coupled with code, so documentation can change automatically as schema types and fields change.
Versionless API evolution	GraphQL eliminates the need for versioning by deprecating API functionality at the field level. Unused fields can be removed from the schema without affecting active queries.
Shared query logic (fragments)	GraphQL fragments are units of query logic that can be shared across multiple queries.
Elimination of over-fetching and under-fetching	GraphQL enables front-end applications to fetch exactly the data they need, when they need it.

Section 3

Fundamentals of GraphQL

Design Principles

GraphQL offers some guidelines for how to think about a service:

Principle	Description
Product-centric	GraphQL is driven by the data needs of the client, the language, and the runtime that supports the client.
Client-specific queries	A GraphQL server provides the capabilities that clients can consume.
Strong typing	A GraphQL server is backed by the GraphQL type system. In the schema, each field has a specific type against which it’s validated.
Hierarchical	A GraphQL schema is hierarchical: Fields are nested within other fields, and queries have the same shape as the data they return.
Introspective	The client can query the GraphQL server’s type system.

Schemas and Types

In GraphQL, a schema defines a collection of types and the relationships between those types. These types and relationships together define the extent of a unified graph. Clients execute queries against this graph to fetch the data they need. The GraphQL schema language, also called the GraphQL Interface Description Language (IDL), is used to define a schema and types.

Type	DESCRIPTION	Example
Object types	An object type that can be fetched, including the fields it provides For example, `Movie` is an object type with fields `title`, `year`, `genres`, and `plot`. `[Movie]` indicates a list of Movie objects, and `!` indicates a non-nullable field.	1 type Movie { 2 id: ID! 3 title: String 4 year: Int 5 plot: String 6 poster: String 7 genres: [String] 8 similar: [Movie] 9 rating: RATING 10 actors: [Actor] 11 series: [Series] 12 avgStars: Float 13 }
Scalar types	Common primitive types The GraphQL specification includes the built-in scalars `Int`, `Float`, `String`, `Boolean`, and `ID` (serialized as a string and can be human-readable). Schemas can also define custom scalars, such as the commonly defined `Date`.	1 1 title: String
Query type	Defines read-only entry points into a graph The Query type defines the top-level fields that are available to clients executing queries. A schema has exactly one Query type.	5 1 type Query { 2 moviesByTitle(title: 3 String!, limit: Int= 4 3): [Movie] 5 }
Mutation type	Defines write entry points into a graph The Mutation type defines the top-level fields that are available to clients executing mutations. A schema can have exactly one Mutation type	4 1 type Mutation { 2 reviewMovie(review: 3 ReviewInput):UserReview 4 }
Enumeration types	A type of scalar restricted to a set of pre-defined values	6 1 enum RATING { 2 G 3 PG 4 PG13 5 R 6 }
Interface types	Abstract type that defines a set of fields that object types can implement Interface types are used when a field might return one of multiple related types.	4 1 interface Person { 2 id: ID! 3 name: String 4 }
Input types	Used to pass complex objects as arguments to a field	5 1 input ReviewInput { 2 rating: Int! 3 movieId: ID! 4 userId: ID! 5 }
Union types	Abstract type that defines a set of object types that all might be returned by a particular field Unlike interface types, members of a union type don't need to define any common fields.	2 1 union PersonResult = 2 User \| Actor

Section 4

GraphQL Queries and Mutations

The fields of the Query and Mutation types are the entry points into a graph. .

Fields

Each type is composed of one or more fields, which can be scalar values or complex objects that refer to other types, resulting in nesting. Each GraphQL query specifies which schema fields to return. This is referred to as the query’s selection set.

Consider the following schema excerpt:

    Java
   
 
type Query { 
  topRatedMovies: [Movie] 
} 
type Movie { 
  id: ID! 
  title: String 
  year: Int 
  plot: String 
  poster: String 
  imdbRating: Float 
  genres: [String] 
  similar(limit: Int = 3): [Movie] 
  rating: RATING 
  actors: [Actor] 
  avgStars: Float 
} 

Here is a valid query against that schema:

    Java
   
 
{ 
  topRatedMovies { 
    title 
    year 
    avgStars 
  } 
}

And here is an example result of that query:

    Java
   
 
{ 
  "data": { 
    "topRatedMovies": [ 
      { 
        "title": "Godfather, The", 
        "year": 1972, 
        "avgStars": 4.4875 
      }, 
      { 
        "title": "Shawshank Redemption, The", 
        "year": 1994, 
        "avgStars": 4.487138263665597 
      }, 
      { 
        "title": "On the Waterfront", 
        "year": 1954, 
        "avgStars": 4.448275862068966 
      } 
    ] 
  } 
} 

Arguments

Schema fields can accept arguments, which can be required or optional. Each argument can optionally have a default value if one isn’t provided.

The following Query.moviesByTitle field accepts two arguments. The limit argument specifies a default value:

    Java
   
 
type Query { 
  moviesByTitle(title: String!, limit: Int = 3): [Movie] 
} 

Here is an example query that provides the required title argument:

    Java
   
 
{ 
  moviesByTitle(title: "Matrix Reloaded") { 
    title 
    similar(limit: 1) { 
      title 
      year 
    } 
  } 
} 

And here is an example result:

    Java
   
 
{ 
  "data": { 
    "moviesByTitle": [ 
      { 
        "title": "Matrix Reloaded, The", 
        "similar": [ 
          { 
            "title": "Matrix, The", 
            "year": 1999 
          } 
        ] 
      } 
    ] 
  } 
} 

Variables

GraphQL variables enable you to provide values for arguments without hardcoding their values directly into a query string. This helps prevent injection attacks that use string interpolation to build queries from user-supplied content. To use variables, first declare $varName as a valid variable for the query, then replace the value in the query with $varName. Finally, pass the key-value pair varName: value in a dictionary alongside the query.

Here’s an example query with two variables:

    Java
   
 
query MoviesByTitle($movieTitle: String!, $similarLimit: Int) { 
  moviesByTitle(title: $movieTitle) { 
    title 
    similar(limit: $similarLimit) { 
      title 
      year 
    } 
  } 
} 

And here’s a variables object that’s provided alongside that query:

    
  
{ 
  "movieTitle": "Matrix Reloaded", 
  "similarLimit": 1 
} 
 
Result: 
{ 
  "data": { 
    "moviesByTitle": [ 
      { 
        "title": "Matrix Reloaded, The", 
        "similar": [ 
          { 
            "title": "Matrix, The", 
            "year": 1999 
          } 
        ] 
      } 
    ] 
  } 
}

Mutations

While queries enable you to read back-end data, GraphQL mutations enable you to create, update, and delete that data. To enable mutations, a schema defines a Mutation type. The fields of this type are entry points that correspond to different write operations that clients can execute.

Consider a UserReview type:

    Java
   
 
type UserReview { 
  user: User 
  rating: Int 
  movie: Movie 
}

To create a new UserReview, a schema might define this Mutation field:

    Java
   
 
type Mutation { 
  createReview(userId: ID!, movieId: ID!, rating: Int): UserReview 
} 

Note that the mutation returns a UserReview object. This means that you can access any of the fields available on Movie and User (in a nested fashion):

Mutation:

    
  
mutation { 
  createReview(userId: "20", movieId: "16", rating: 5) { 
    movie { 
      title 
      similar(limit: 2) { 
        title 
      } 
    } 
    user { 
      name 
    } 
    rating 
  } 
} 

Result:

    
  
{ 
  "data": { 
    "createReview": { 
      "movie": { 
        "title": "Casino", 
        "similar": [ 
          { 
            "title": "Four Brothers" 
          }, 
          { 
            "title": "Night and the City" 
          } 
        ] 
      }, 
      "user": { 
        "name": "Nicole Ramsey" 
      }, 
      "rating": 5 
    } 
  } 
} 

Input Types

In the previous mutation example, three individual primitive arguments were passed to the createReview field. Instead, this field could accept a single input type that includes all of those individual primitive values as fields. Input types are especially useful for mutations where the goal is to pass an update as a single object.

Input type:

    
  
input ReviewInput { 
  rating: Int! 
  movieId: ID! 
  userId: ID! 
} 

Then modify the createReview field to accept one argument of type ReviewInput:

    
  
type Mutation { 
  createReview(review: ReviewInput!): UserReview 
} 

The mutation becomes:

    
  
mutation CreateReviewForMovie($review: ReviewInput) { 
  createReview(review: $review) { 
    movie { 
      title 
    } 
    user { 
      name 
    } 
    rating 
  } 
} 

Variables:

    
  
{ 
  "review": { 
    "movieId": "16", 
    "userId": "20", 
    "rating": 5 
  } 
} 

Results:

    
  
{ 
  "data": { 
    "createReview": { 
      "movie": { 
        "title": "Casino" 
      }, 
      "user": { 
        "name": "Nicole Ramsey" 
      }, 
      "rating": 5 
    } 
  } 
} 

Fragments

A fragment is a reusable set of fields that can be defined and referenced by name in multiple GraphQL queries. This enables you to factor out common logic and reduce repetition in operations. To apply a fragment inside a query, use a fragment spread operator (...) inside the selection set:

    
  
{ 
  moviesByTitle(title: "Matrix Reloaded") { 
    ...movieSummaryFields 
  } 
} 
fragment movieSummaryFields on Movie { 
  title 
  year 
  imdbRating 
} 

Result:

    
  
{ 
  "data": { 
    "moviesByTitle": [ 
      { 
        "title": "Matrix Reloaded, The", 
        "year": 2003, 
        "imdbRating": 7.2 
      } 
    ] 
  } 
} 

Inline Fragments

Inline fragments are useful for queries where a field’s return type is determined at runtime. These fragments use the syntax ...on <TYPE>. They are primarily used when a field’s return type is an abstract type (i.e., a union or interface).

Consider the following:

    
  
type Query { 
  personByName(name: String!): [PersonResult] 
} 
union PersonResult = User | Actor 

PersonResult can be either a User or Actor. In this case, an inline fragment can be used to fetch the appropriate fields for each type in the union:

    
  
{ 
  personByName(name: "Tom Cruise", limit: 3) { 
    ... on Actor { 
      name 
      movies { 
        title 
      } 
    } 
    ... on User { 
      name 
    } 
  }
} 

Result:

    
  
{ 
  "data": { 
    "personByName": [ 
      { 
        "name": "Tom Cruise", 
        "movies": [ 
          { 
            "title": "Risky Business" 
          }, 
          { 
            "title": "Cocktail" 
          }, 
          { 
            "title": "Top Gun" 
          } 
        ] 
      } 
    ] 
  } 
} 

Subscriptions

Often, clients want to receive updates from the server when certain data changes. In addition to queries and mutations, GraphQL supports a third operation type, subscription, which allows a client to subscribe to receive event updates. Subscriptions are real-time streaming chunks of data that allow bi-directional interaction over a single persistent connection (often WebSocket).

Let's say a client wants to receive updates when a user submits a movie rating for a particular movie. If the user is viewing a movie page, the UI would update when a new rating is received.

Every time the underlying MovieReviewSubscription is changed, the new value for rating will be pushed over WebSocket (or some other type of persistent connection). The nature of operations performed by subscription is slightly different than that of query — the former has real-time fetching of data while the latter fetches only once.

Subscription operation:

    
  
subscription MovieReviewSubscription($movieId: ID!) { 
  movieReviewSubscription(movieId: $movieId) { 
    movie { 
      title 
    } 
    rating 
  } 
} 

Directives

GraphQL directives enable static and dynamic schema modification. Here are two built-in directive examples:

@skip

@include

         
       
query myMovieQuery($testValue: Boolean!) { 
  experimentalField @skip(if: $testValue) 
} 

In this example, experimentalField is queried only if the variable $testValue has the value false.

         
       
query myMovieQuery($testValue: Boolean!) { 
  experimentalField @include(if: $testValue) 
} 

In this example, experimentalField is queried if the variable $testValue has the value true.

Learn more about directives here.

Securing Your GraphQL APIs

Failing to secure APIs properly can have serious consequences, especially with GraphQL. Because clients can craft complex queries, servers must be ready to handle such queries. Certain queries might be abusive or malicious, or they might simply be very large. In all of these cases, the query can potentially bring down your GraphQL server. GraphQL recommends a few guidelines and strategies.

Timeout

Setting a timeout informs a server and any intermediaries of the maximum amount of time they can spend to execute any query. If a query exceeds this maximum, the server ceases execution.

Limiting Maximum Query Depth

GraphQL schemas are often cyclic graphs, meaning a malicious GraphQL query can exploit nested relationships. For example, let’s say there’s an Entertainment API that exposes an Actor type. Each Actor can belong to a Movie, and each Movie can have an Actor in the form of an Artist. Considering this, a deeply nested query such as the following is valid:

A circular reference like this can lead to significant load on API servers.

GraphQL servers can enforce depth-limiting caps to control the amount of nesting that can be present in any given query. Before the query is processed, its depth is calculated (the above query has six nesting levels). If the nesting depth exceeds the given limit, it is rejected outright.

Query Complexity Limits

Another troublesome query relates to complexity — for example, a client can simply request many fields on the root query object.

To deal with this kind of query, GraphQL has built-in support for complexity analysis. An arbitrary number can be assigned as points to any field. When an incoming query is received, these arbitrary numbers are summed. If the total exceeds the threshold, an appropriate error message is returned.

Field-Based Permissions

Given a schema with the objects Users, Bookings, and Movies, the Bookings and Users objects are private, so authentication is needed to access them. Authentication is handled by resolvers. The Movies object is public and can be accessed without being authenticated. Now, what should happen with the query below if the client is not authenticated?

Section 5

Assuming that the client making the query above isn’t authenticated, they can access all of the user’s data, which breaches user privacy. The problem above is solved by adding a permission on the query, object, and field level.

Permission on field level allows you to add a check over the field. Let’s say for the object User, some fields can be viewed by anyone like name, but we don’t want to show the field Booking, as this data is considered private and only accessible by the User or Admin.

Logic inside resolver:

When a field is restricted and used in a GraphQL operation, the consumer receives an error response (e.g., 400 Bad Request).

Section 6

Conclusion

While this Refcard covered the primary benefits of GraphQL and introduced some essential GraphQL concepts, as well as more advanced fundamentals, there are still many topics left to explore. Below is an overview of additional resources available to learn more about GraphQL and tools to simplify the process of building GraphQL applications:

Graphql.org – Portal for all things GraphQL
GraphQL specification – A working draft of the GraphQL specification, maintained by Facebook
Apollo Client and Server – Flexible GraphQL libraries for back-end and front-end applications
Apollo Odyssey – Interactive, in-depth tutorials for getting started with GraphQL
Sandbox – In-browser IDE for exploring GraphQL endpoints
graphql-tools – Opinionated structure for how to build a GraphQL schema and resolvers in JavaScript, following the GraphQL-first development workflow
Prisma – Open-source database toolkit
DataLoader – Utility for batching and caching requests, often used with GraphQL services
PostGraphQL – Create a GraphQL API by reflection over a PostgreSQL schema
Awesome GraphQL – A collection of links to GraphQL resources including tutorials, libraries, and examples