About GraphQL API

Owned by Patricia Donohue
Last updated: Feb 10, 2023
6 min read

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.

 

What is GraphQL?

GraphQL is a new API standard that provides a more efficient, powerful and flexible alternative to REST (Representational State Transfer)*. *Courtesy of GraphQL EdEx Course

A data query language for APIs that can be used with any language and framework. It can be used anywhere a client communicates with an API and makes API communications more efficient. GraphQL was developed to meet the need for more flexibility and efficiency in client/server communications. 

You can use GraphQL (via a single endpoint) to:

  • Retrieve data (via a “query”)

  • Add, update, or delete data (via a “mutation”)

  • Specify the exact data you want

GraphQL is a new API standard that provides a more efficient, powerful and flexible alternative to REST (Representational State Transfer)*.

 

Recommended

There 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:

  1. Popular way for client’s to retrieve data using HTTP

  2. Introduced ideas like stateless server and structured resource access

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

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

 

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.

  • updatePerson takes an ID so we can specify which person to update and pass in the person’s properties as arguments

  • deletePerson only takes an ID to tell the server which person to delete

 

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

  1. Apollo Server is a library that connects a GraphQL schema to an HTTP server (in Node.js and other server languages).

  2. GraphiQL

  3. GraphQL Hub