GraphQL is not a database, nor a library. Simply put, it is a runtime combined with a language for querying and accessing the backend data. We use it mostly to implement experience layer APIs where the response can match only the data that is needed by the client. It's really good when you need the data to drive the user interface, like when you have a data structure that multiple users are making changes to and you need to make updates to the view in real time.

The client sends queries that are evaluated against a predefined schema, which is a type system created and designed by ourselves. This defines what is possible for users to query, similar to an interface specification. It's here where you define all of the fields and data types available.

Here's an example of a simple schema. The schema shows two object types defined—Hello and User:

type Hello {
    user: User
}

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

A schema defines the relationships between types. In the preceding example, every Hello object has User. There are five categories of types in a GraphQL schema:

• Scalar: This is a primitive type such as an integer or a Boolean.
• Object: This is a collection of fields that can be either a scalar type or another object type.
• Query: This defines the possible read queries that a client can perform against the data.
• Mutation: This defines the possible write queries that a client can perform against the data.
• Input: This is a special type that allows you to pass arguments, parameters, or other objects to queries and mutations.

The schema itself is an abstraction from the underlying infrastructure implementation so it does not define where or how the data is stored.

The schema also supports native versioning and that is another big benefit over REST. Instead of versioning the endpoint, it's more focused on managing individual fields. You can add fields with no impact on the consumers, but you still need to be careful about maintaining backward compatibility. There's a @deprecated directive that can mark fields that are no longer used, which is cool. 

With an inherent filtering function in the queries, you can just ask for what you want in your request. This cuts down the over- or under-fetching tendency that you get with REST. A query is a read operation and allows a client to ask for the exact data it needs, in the structure that it wants. Here's an example query following the preceding schema.

The (very basic) query language shown in the following code is passed during the request and is querying for the name field within the User object that the Hello object has a relationship with:

{ 
    hello { 
        name 
    } 
}

The preceding could return some JSON like this: 

{
  "hello": {
    "name": "Scott Patterson"
  }
}

The runtime or engine behind the query language parses your query into a graph, and then uses each node in the graph to run resolvers to fetch the data from the source. Resolvers are functions and templates that interface with data sources. Each resolver represents one field of the data, and the resolver function knows how to retrieve that field from each data source. An example of a data source could be a database table, a cache, or even a RESTful API.

We've covered reading data, but how about writing? A mutation is a GraphQL write operation, much like PUT, POST, or DELETE. They are the things that a user can do with your data.

An example using our schema could look like the following. It's almost the same as a query, but this time we've added an input type to simplify the syntax:

type Mutation {
    createUser(data: CreateUserInput): User!
}

input CreateUserInput {
    name: String
    age: Int
}

And to run that in the query language would be as follows:

mutation makeAHelloUser {
    createUser(
        name: "Scott Patterson"
        age: 10000
    ) {
        name
        age
    }
}

So, there are the basic concepts of the query language, queries, mutations, and the schema. Next, we're going to move on and introduce a managed GraphQL service that we can use to create our own APIs.