Running examples

The examples documented here can be run using:

• Our Playground.

• The command line.

Command line

You can run GraphQL queries in a curl request on the command line on your local machine. A GraphQL request can be made as a POST request to https://api.kublau.com/graphql with the query as the payload. You can authorize your request by using a test API key to use as a bearer token.

Example:

GRAPHQL_TOKEN=<ACCESS_TOKEN>
curl "https://api.kublau.com/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {workspace {name}}\"}"

Queries and mutations

The Kublau GraphQL API can be used to perform:

• Queries for data retrieval.

• Mutations for creating, updating, and deleting data.

Note: In the API, id refers to a global ID, which is an object identifier in the format of gid://kublau/ObjectType/xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

Kublau’s GraphQL Schema outlines which objects and fields are available for clients to query and their corresponding data types.

Example: Return a Workspace resource corresponding to the API Key used in request.

query {
  workspace {
    id
    name
  }
}

Mutations

Mutations make changes to data. We can update, delete, or create new records. Mutations generally use InputTypes and variables, neither of which appear here.

Mutations have:

• Inputs. For example, arguments, such as which carrier you’d like to use when creating a shipment.

• Return statements. That is, what you’d like to get back when it’s successful.

• User errors. Always ask for what went wrong, just in case.

Creation mutations

Example: Let’s create a shipment Tracker.

mutation createTracker {
  trackerCreate(input: {
    trackingCode: "K1000000000",
    carrier: ESTAFETA
  }) {
    tracker {
      id
      trackingCode
      status
      estimatedDeliveryAt
      deliveredAt
      carrier
      checkpoints {
        id
        message
        status
        scannedAt
      }
    }
    trackerUserErrors {
      code
      message
      field
    }
  }
}

More about mutations: GraphQL Docs.

Introspective queries

Clients can query the GraphQL endpoint for information about its own schema. by making an introspective query.

It is through an introspection query that the GraphiQL Query Explorer gets all of its knowledge about our GraphQL schema to do autocompletion and provide its interactive Docs tab.

Example: Get all the type names in the schema.

{
  __schema {
    types {
      name
    }
  }
}

Example: Get all the fields associated with Tracker. kind tells us the enum value for the type, like OBJECT, SCALAR or INTERFACE.

query TrackerTypes {
  __type(name: "Tracker") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

More about introspection: GraphQL docs