Getting started with Jungle API

Learn how to use the docs and interact with the API.

Running examples

The examples with in the documentation can be run using:

• The command line.
• GraphQL Playground.

Command line

You can run GraphQL queries using curl in the command line on your local machine. An operation can be initiated as a POST request to /graphql with the query as the body.

Example:

JUNGLE_APIKEY='{JUNGLE_APIKEY}'
curl 'https://ape.cafe/graphql' \
  -H "Authorization: ApiKey ${JUNGLE_APIKEY}" \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ now }"}'

GraphQL Playground

The GraphQL playground allows you to run queries directly against the API with syntax highlighting and autocompletion. It also allows you to explore the schema and type documentation.

Operations

The API can be used to perform:

• Queries for retrieving data.
• Mutations for creating, changing, and deleting data.

Queries

Queries retrieve data from the server, and will not modify account state.

Example: Get a specific order and one of it's fulfilments.

query OrderRead {
  order(orderId: "oLaC8A21IYlG8DwMW5C8") {
    reference
    fulfilments {
      service {
        name
      }
    }
  }
}

Example: List the names of all the locations the current user can access (up to a limit, more on that later)

query DocsLocationList {
  locationList(input: { limit: 3 }) {
    pageInfo {
      nextCursor
    }
    results {
      location {
        id
        name
      }
    }
  }
}

Mutations

Mutations make changes to data, and will modify account state.

Mutations have:

• Inputs. For example, arguments, such as which location you'd to like create a collection from.
• Return queries. That is, what data you'd like to get back when the mutation is successful.
• Errors. What went wrong, which you should always ask for just in case.

Example: Add a new product to the account.

mutation ImportProduct {
  productCreate(input: { barcode: "1000012", name: "widget" }) {
    alreadyExisted
    product {
      id
      description
    }
  }
}

Subscriptions

Subscriptions push data from the API, or notifications to subscribed clients.

Subscriptions have:

• Filters. For example, arguments, such as which order statuses you would like notifications for.
• Selection query. That is, what data you'd like to be sent when the action is triggered.

Example: For testing, get broadcast times from Jungle.

subscription {
  now
}

ℹ️ Subscriptions require a WebSocket connection to the API endpoint. wss://

Introspective queries

Clients can query the API for information about it's own schema by making an introspective query.

It is through an introspection query that the playground obtains its knowledge of the GraphQL schema to do autocompletion and provide its interactive Docs tab.

Schema introspection allows features like client type generation, an extremely useful tool for integrators. Schema visualization, to easily understand the relationships with in the schema.

Example: Get all the type names in the schema.

{
  __schema {
    types {
      name
    }
  }
}

Example: Get all the fields associated with Order.

query OrderTypes {
  __type(name: "Order") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

😃 Schema and introspection queries against the GraphQl API do not require authentication.

Concepts

There a number of API concepts that are common enough to be highlighted.

Ordering

Ordering is a way change what property to sort list queries, and in which direction.

Pagination

Pagination is a way of asking for a subset of records (say, 10). If we want more of them, we can make another request for the next 10 from the API.

By default, the GraphQL API will return only the first 20 records of any result set. This can be changed by using limit argument. The limit argument takes a number value, so limit: 10 will return 10 records.

Example: Retrieve only 2 of your locations.

query DocPagingExample {
  locationList(input: { limit: 2 }) {
    results {
      location {
        name
        address {
          lines
          postalCode
        }
      }
    }
    pageInfo {
      hasMore
      nextCursor
    }
  }
}

🤖 limit is clamped to a maximum value of 50.

Example: Retrieve the next 2 of your locations using cursor.

query DocPagingExample {
  locationList(input: { limit: 2, cursor: "VDRDa2ZYbThkNlV3TUlyVVpCbnM=" }) {
    results {
      location {
        name
        address {
          lines
          postalCode
        }
      }
    }
    pageInfo {
      hasMore
      nextCursor
    }
  }
}

🤖 The input cursor value comes from the nextCursor of the previous response.

Now that you have an overview of the API, you should find a relevant use case for further study, or jump straight in! 🥳