About GraphQL

Delivery Gateway uses GraphQL for building its API. This guide walks you through the basics of GraphQL.

About GraphQL

GraphQL is a query language and runtime system. Clients send requests to GraphQL services by using the GraphQL query language, and the service returns the data in a response.

A GraphQL API has a single endpoint for all data. The GraphQL type system describes the data that can be requested from the API. The collection of those data descriptions is called the GraphQL service's schema.

To read or write data, the client must form GraphQL requests using the types defined in the service's schema:

• Queries: Requests to retrieve data. Essentially, the client is asking for specific fields on pre-defined objects. They're similar to a GET request in a REST API.
• Mutations: Requests to create and update data. They're similar to a POST or PATCH method in a REST API.

Queries

A GraphQL query requests data from specific fields of one or more objects defined in the schema of the GraphQL service.

The GraphQL request format is similar to JSON but it doesn't use quotation marks for field names. GraphQL services return responses in JSON format. A simple query and response could look something like this:

GraphQL query

query {
  providers {
    id
    name
  }
}

JSON response

{
   "data": {
      "providers": {
         "id": "RIV",
         "name": "Red Ivorp"
      }
   }
}

All GraphQL operations start with a root operation type: in this case, it's query. From there you specify the selection set of fields you're interested in: in the example, we're requesting the data from the sender_name field of the merchant object.

The request's result will be returned in a top-level data key. If the request raised errors, the relevant information will be included in a top-level errors key.

Arguments

A GraphQL service can pass arguments to fields: this means that the client must provide a value for the required argument when sending a query. For example, you can specify the ID of a provider to query pick-up point availability:

GraphQL query

query {
  shipment(id: 215099) {
    provider
    mode 
  }
}

JSON response

{
   "data": {
      "shipment": {
         "provider": "Red Ivorp",
         "mode": "SENDER_TO_RECIPIENT"
      }
   }
}

Mutations

In a REST API, you send a POST request to a specific endpoint to create or update data. In GraphQL, you use mutations. Mutations are sent to a single endpoint and use the POST HTTP method.

A GraphQL mutation requires:

• A mutation field name: for example, updateMerchantConfiguration. They are defined in the GraphQL schema.
• Input data passed as an argument to the mutation field. This is the data that you create or modify.
• A list of fields that should be included in the JSON response. GraphQL nly returns the data you specifically ask for.

In the example, we set a new sender_name for a merchant with the updateMerchantConfiguration mutation and request that the GraphQL API returns the new sender_name and the sender_email fields.

GraphQL mutation

mutation {
  createZone(
    input: {
      name: "Hungary",
      countries: HU
    }
  )
  {
    id
    name
    countries
  }
}

JSON response

{
   "data": {
      "createZone": {
         "id": "45678",
         "name": "Hungary",
         "countries": [
            "HU"
         ]
      }
   }
}

Variables

Variables allow you to reuse the same GraphQL requests with dynamic values. Variables are declared after the query or mutation keyword, like passing an argument to a function. They always begin with the $ symbol.

A variable declaration works this way:

• Declare a $variableName.
• Specify the type of the variable, for example, createShipmentInput!.
• Replace the static value in the query or mutation with $variableName.

mutation($input: createShipmentInput!) {
  createShipment(input: $input) {...}
}

Define the actual values for the variable in a separate variables dictionary that's usually in a JSON format.

{
   "input": {
      "provider":"Pro Vider",
      "referenceId":"12345",
      "recipient":{
         "firstName":"Fictitious",
         "lastName":"Customer",
         "language":"EN"
      },
      "destination":{
         "pickupPointId":"12345"
      }
   }
}