Introduction to GraphQL
Authors:
Ankit Mehta, Movyn John, Cille Schliebitz, Anita Gu
Changed on:
3 Feb 2025
Overview
In this lesson, we'll look at the benefits of using GraphQL, as well as explore the differences between GraphQL and REST based APIs. We will also look at some examples of a GraphQL query and a GraphQL mutation.
Key points
- Introduction to GraphQL
- Differences to REST
- Benefits of using GraphQL
- Basic structure of a query
- A GraphQL mutation
- Types of common integrations that use GraphQL
Introduction to GraphQL
- GraphQL is an open-source data query and manipulation language for APIs and a runtime for fulfilling queries with existing data. It was developed by Facebook and released to the public in 2015.
- The objective of GraphQL is to reduce the amount of data that's going over the wire and for the calls that are made, to be as specific as possible.
For developers who've used REST-based APIs in the past, here are some key differences to note:
- GraphQL is always a POST HTTP Method.
- GraphQL returns 200 OK HTTP Status, even if errors occur. Errors will be in the Response body.
- GraphQL queries that do not find any result, respond as 200 OK, and a data object with null or empty entity field.
- GraphQL schema provides strongly typed validation and includes documentation.
- GraphQL allows querying multiple entities in a single HTTP request.
Next, let's look at the benefits of using GraphQL.
Benefits of Using GraphQL
To understand the benefits, let's look at GraphQL from an Efficiency, Flexibility, Unification and Introspection & Validation standpoint.
Efficiency | GraphQL allows the API client to send multiple queries or mutations within a single HTTP request. This reduces network latency and chattiness and allows developers to retrieve or write the specific data they need at once if it makes optimal and logical sense to do so. |
Flexibility | Retrieving data from the server can be done in a Query Language-like approach, where the API client defines which fields and objects they would like to receive, rather than being forced to retrieve predefined Data Transfer Objects, as is typical with REST-based APIs. |
Unification | In addition to being highly efficient, GraphQL provides the ability to query multiple data objects and declare the fields to be returned for each data object, allowing developers to work with unified data objects on the client side. |
Introspection & Validation | GraphQL APIs provide a schema that allows clients to introspect and validate their queries, mutations, and overall interaction with the API on the client side before executing or sending the HTTP request. |
Structure of a GraphQL Query
Query operations are used for retrieving data. GraphQL provides two types of query operations:
- Get: To retrieve an entity with a unique identifier and display results
- Search: To search and display a list of results, while applying some filters
Seen below is a simple GraphQL query.
order vs orders | For a Get command, we would say Order. And, a Search will always end with an S in our schema. Here 'orders' is used as we're searching through the orders. |
status: "BOOKED" | This is an example of a GraphQL query that retrieves all orders that are currently under the status "BOOKED". |
First 100 records | "first: 100" means that it will retrieve the first 100 orders. So, if there are more than 100 orders, then it would only get the first 100. This is one of the paging-based parameters, GraphQL uses cursor-based paging, and you can also use 'last'. |
Edges and Nodes | When searching through records, we will always get edges and nodes, where each node represents a result of that Search. But, for the Get command, there wouldn't be edges and nodes, instead the specified fields will be returned. |
By default, every GraphQL query will return 10 results unless the count is specified using 'first' or 'last'. The maximum count for this 'first' or 'last' is 5000, and the use of pagination is recommended to extract a larger data set.
Please consider the Query Complexity while writing your query, as per the information posted here (opens in a new tab).
GraphQL Mutations
Mutation operations are used for creating and updating data. All mutation operations take a single parameter and have the following naming convention:
<<mutationName>>(<<MutationNameInput>>):<<Type>>
Create: Create mutations are used to create new data.
- Input types for Create mutations have mandatory parameters that are used to define the entity to be created uniquely.
- All entities of orchestrate-able types fire orchestration events on creation. This can be used to trigger workflows.
- Every Create mutation creates the entity in the “CREATED” status. This enables the clients to trigger orchestrations for that entity if the client wishes to change the status of that entity after creation using workflow.
Update: Update mutations are used for updating existing data.
- Input types for update mutations have mandatory parameters that are used to identify the object to be updated uniquely.
Examples
Create Order Mutation:
1mutation {
2 createOrder(input:{
3 ref:"HD_2341"
4 type:"HD"
5 retailer:{id:1}
6 customer:{id:34}
7 items:[{
8 ref:"VPRD_13"
9 productRef:"VPRD_13"
10 quantity:2
11 }]
12 }){
13 id
14 createdOn
15 }
16}Language: json
Name: Json Snippet
Description:
The above mutation creates an order of type HD with 1 item - VPRD_13
Update Order Mutation:
1mutation {
2 updateOrder(input:{
3 id:5432
4 status:"BOOKED"
5 }){
6 id
7 createdOn
8 }
9}Language: json
Name: Json Snippet
Description:
The above mutation updates the status of order to BOOKED
Some common integrations that use GraphQL are:
- Order Create:
Order creation from the Sales Channels - Product Availability:
Extracting Virtual Positions to be used for PLP pages or Search results - Reporting:
Extracting orders / fulfillments for reporting purposes - Light Webhooks:
In order to achieve lightweight webhooks, the Webhook should only contain the entityID, but then the system to be integrated will need to extract the entity details using a GraphQL query
