Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

Introduction to Integrations and Connections

Introduction to the Events API

End Of Track

Content in this track: Introduction to GraphQL

Essential knowledge

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 GraphQLTo understand the benefits, let's look at GraphQL from an Efficiency, Flexibility, Unification and Introspection & Validation standpoint. No alt provided

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 QueryQuery 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. No alt provided

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 MutationsMutation operations are used for creating and updating data. All mutation operations take a single parameter and have the following naming convention:<<mutationName>>(<<MutationNameInput>>):<<Type>> No alt provided

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.

ExamplesCreate 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}

Update Order Mutation:

1mutation {
2 updateOrder(input:{
3     id:5432
4     status:"BOOKED"
5 }){
6     id
7     createdOn
8 }
9}

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