Introduction to 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.

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.

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}

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