GraphQL

From https://graphql.org:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.
GraphQL provides:

• a complete and understandable description of the data in your API,
• gives clients the power to ask for exactly what they need and nothing more, (vs REST)
• makes it easier to evolve APIs over time,
• and enables powerful developer tools.

A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type.

On the other side, REST is resource-based. Every resource, for example a book, has its own address which identifies it, for example /books/42. All operations done to the resource are done with HTTP requests to its URL. The action depends on the HTTP method used.

GraphQL forms a query describing the data wanted, and sends it to the API with an HTTP POST request. Unlike REST, all GraphQL queries are sent to the same address, and their type is POST.

Some definitions:

Fields

GraphQL is about asking for specific fields on objects, e.g. "ask for the value of a prop". Fields can refer to several types (String, Int, etc.) or objects, in which case you can make a sub-selection of fields. GraphQL queries can traverse related objects and their fields, letting clients fetch lots of related data in one request, instead of making several roundtrips as one would need in a classic REST architecture.

GraphQL Query	Returned Data
{ hero { name } }	{ "data": { "hero": { "name": "R2-D2" } } }

Arguments

In a system like REST, you can only pass a single set of arguments - the query parameters and URL segments in your request. But in GraphQL, 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.

Schema

Map the relationships among data points on the graph. Every GraphQL service defines a set of types that 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. A schema contains

• types,
• relationships among types,
• root query,

Types

Object types are the basic components of a GraphQL schema.
They represent a kind of object you can fetch from your service, and what fields it has.

type Character {
  name: String! // name is a field on the Character type
  age: Int
  isEvil: Boolean!
}

Query

Query is one of the three operation types allowed in GraphQL: query, mutation, or subscription. Using query allows fetching data from a server.

Mutations

Mutation is one of the three operation types allowed in GraphQL: query, mutation, or subscription. Using mutation allows for modifying data on a server.
As a convention "any operations that cause writes should be sent explicitly via a mutation".
Note that it is possible to mutate and query a new value of a field with one request.

• Root Query: "path" that allows to query the graph to reach nodes