GraphQL Essentials

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

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

Design Principles

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

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 Movie { 
id: ID! 
title: String 
year: Int 
plot: String 
poster: String 
genres: [String] 
similar: [Movie] 
rating: RATING 
actors: [Actor] 
series: [Series] 
avgStars: Float 
} 

title: String 

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

type Mutation { 
reviewMovie(review: 
ReviewInput):UserReview 
} 

enum RATING { 
G 
PG 
PG13 
R 
}

interface Person { 
id: ID! 
name: String 
} 

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

union PersonResult = 
User | Actor 

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: 

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: 

{ 
  topRatedMovies { 
    title 
    year 
    avgStars 
  } 
}

And here is an example result of that query:

{ 
  "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: 

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

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

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

And here is an example result:

{ 
  "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: 

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: 

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

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

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: 

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

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

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? 

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

 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