Interacting With The API

The API is served over TCP, leveraging the existing infrastructure of HTTP. GraphQL adds a powerful query layer to give you complete control over the request, including the shape of the data in the response.

Pagination

Result sets are limited to 100 results. You must use the combination of order_by, limit, and offset query params to paginate through larger result sets. The first query should have a 0 offset, then increment by the limit.

Setup

Set up a local stack using docker compose, or use a public deployment.

GraphQL Playground to Develop a Query

The GUI provides a nice query development environment, complete with generated docs, and the schema to review. Once happy with the results, the query can be extracted as a formatted curl command.

Example output

curl 'http://localhost:3100/' -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Connection: keep-alive' -H 'DNT: 1' -H 'Origin: http://localhost:3100' --data-binary '{"query":"query utxoAggregateValueLessThan (\n    $boundary: String\n){\n    utxos_aggregate( where: { value: { _lt: $boundary }}) {\n        aggregate {\n            avg { value }\n            count\n            max { value }\n            min { value }\n            sum { value }\n        }\n    }\n}","variables":{"boundary":"500"}}' --compressed

Command Line

You can use graphqurl from the Hasura team to facilitate command line interactions with GraphQL. Graphqurl provides features like autocomplete, subscriptions, and GraphiQL, making it a versatile and user-friendly tool.

However, you can also interact directly with the API using curl. Below are examples of how to perform queries with curl.

Example Command Using Curl

curl -X POST \
-H "Content-Type: application/json" \
-d '{"query": "{ cardano { tip { number slotNo epoch { number } } } }"}' \
http://localhost:3100/graphql

Example Response

{
  "data": {
    "cardano": {
      "tip": {
        "number": 4391749,
        "slotNo": 4393973,
        "epoch": {
          "number": 203
        }
      }
    }
  }
}

Request Within an Application

const query = `
  query getTransactions(
    $limit: Int,
    $offset: Int,
    $where: Transaction_bool_exp
  ) {
     transactions(
      limit: $limit,
      offset: $offset,
      where: $where
    ) {
      fee
      block {
        number
      }
      id
    }
  }`

const limit = 100
const offset = 2
const where = {
  block: {
    number: {
      _gte: 50
      _lt: 100
    }
  }
}

fetch('/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    query,
    variables: { limit, offset, where },
  })
})
  .then(r => r.json())
  .then(data => console.log(`Page ${offset} containing ${limit} transactions:', data))

Stateful client

Cardano Explorer serves as a working example.