Interacting With The API

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.

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.

Detailed below are some approaches for connecting and interacting with the API, however there may be other ways more suited for your use-case.

Setup 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

graphqurl from the Hasura team is

curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.

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

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

Request within app

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.