| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
The Fraud Data API is developed using GraphQL technology. There are many resources available to help you learn GraphQL including Introduction to GraphQL which we highly recommend. |
...
Introduction
...
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
|
...
RecommendedThere are many online resources available to help you learn GraphQL. |
...
The CCCTC recommends Introduction to GraphQL - an excellent primer containing articles and examples that explain essential GraphQL concepts and how they work. |
...
GraphQL also |
...
hosts a Community page full of resources to reference and groups to join. For more practical guides, visit the How to GraphQL tutorial website. They also have a free online course with edX, Exploring GraphQL: A Query Language for APIs. |
GraphQL vs. REST API
Components of GraphQL:
Has a schema
Uses some different terms from REST (i.e. “mutation” to perform CRUD operations (i.e. POST in REST); “query” instead of GET, etc.)
Different approach from REST (more work is done on the server side instead of the front end)
...
REST has been the standard for designing web APIs for the last decade. It is:
Popular way for client’s to retrieve data using HTTP
Introduced ideas like stateless server and structured resource access
Has a strict specification for how servers will make data available, but in practice has been widely interpreted/implemented
GraphQL Schema & Type System
GraphQL is organized in terms of schema and type system versus Rest API endpoints.
...
The
...
schema is one of the most important concepts when working with a GraphQL API. It specifies the capabilities of the API, the shape of the available data, and the specific queries and mutation functions that can be used to read, write and make web requests from a GraphQL server. GraphQL enables users to specify exactly what data they get back in their response—nothing more, and nothing less, and it allows querying for multiple fields in a single request.
Often seen as a contract between the server and the client
In general, a schema is simply a collection of GraphQL types
Each schema will have some root types that define the entry points for the API:
Query
Mutation
Subscription.
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
GraphQL has its own type system that’s used to define the schema of an API. The syntax for writing schemas is called Schema Definition Language (SDL). |
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
Below are examples of how we would have to define these types in the schema to enable the examples above. |
Query Types in the GraphQL Schema
To enable an allPersons query...
We need to add a corresponding field to the query type.
Note that we also add the last parameter (that were used at some point in an earlier example) to limit the number of users that we wanted to retrieve.
Mutation Types in the GraphQL Schema
Similar to the query, for a mutation to create a new person, we have to add the createPerson field to the mutation type (since that was the root field that we used when we were sending the mutation).
It takes the name and age arguments (that we used in the example before).
In the return type of the createPerson mutation (the createPerson field) is a single person object.
Logically, this is the one that was created by the mutation.
Subscription Types in the GraphQL Schema
The root field that we used to subscribe to the event of new person being created was called newPerson.
The newPerson field needs to be added to this subscription type in our schema. The type of the newPerson field is Person.
Full Schema Example
The example below demonstrates the full schema that defines all the capabilities of this API example. It's based on the model of the Person and the Post types, and the three root types (allPersons, createPerson, newPerson) from above are defined.
It’s still not a fully-realistic example yet though as:
despite having defined the Post type in the schema, the API actually does not allow any operations on it at the moment.
All we can do with the API right now is to read the list of allPersons, create new persons (createPerson) and subscribe to the event of new persons being created.
To illustrate the general ideas to follow when writing a GraphQL schema, the below provides a more complete GraphQL example, with more realistic API capabilities using these components, and defines additional operations (CRUD) for both Person and Post model types.
The updates in the above example include:
Added... | To... |
Another field to the query type (allPosts) | Retrieve all the stored posts from the server Note: we can now ask for all posts and all the persons but still can’t query individual posts or persons objects. |
CRUD features for Person type | Allow create/read/update/delete functionality for the Person type by adding two mutations: one to update and one to delete the Person object.
I.e. create, read, update, delete = the four kinds of operations we can perform on a type |
CRUD features for Post type | Add the create, update and delete mutations for the Post type, analogous to how they were specified them for the Person type above. Note: An ID was added to the Post type for the create and delete mutations to work. |
Subscriptions to the Person and Post types just added | Clients can be notified of these actions |
Note that it's not really possible to set and modify the relation between the Person and Post types. To do that you’d need to do the following:
type Post {
id: ID!
title: String!
author: Person!
GraphQL SDL
Simple types example below: Person and Post.
type: Person | type: Post |
has two fields: name and age | had one field, title, and in the image below, a relation was added to it by adding the field author |
The name and age fields are of the types String and Int, respectively Note: The ! means the field is required. | The title field is of type String and the author field is a relation indicating that every post that’s created has to have one person who is its author. |
GraphQL Related Tools
Tools associated with GraphQL that may be helpful (and why you might want to use them):
Apollo Server is a library that connects a GraphQL schema to an HTTP server (in Node.js and other server languages).
GraphiQL
GraphQL Hub