input-output-hk / Cardano Graphql

Cardano GraphQL

Overview

Cross-platform, typed, and queryable API for Cardano. The project contains multiple packages for composing GraphQL services to meet specific application demands, and a docker-compose stack serving the included cardano-graphql-server Dockerfile and the extended hasura Dockerfile. The schema is defined in native .graphql, and used to generate a TypeScript package for client-side static typing.

Apollo Server exposes the NodeJS execution engine over a HTTP endpoint, and includes support for open source metrics via Prometheus, and implementing operation filtering to deny unexpected queries. Should you wish to have more control over the server, or stitch the schema with an existing service, consider importing the executable schema from the @cardano-graphql/api-* packages only.

GraphQL is a query language and execution environment with server and client implementations across many programming languages. The language can be serialized for network transmission, schema implementations hashed for assurance, and is suited for describing most domains.

TypeScript (and JS) has the largest pool of production-ready libraries, developers, and interoperability in the GraphQL and web ecosystem in general. TypeScript definitions for the schema, generated by GraphQL Code Generator, are available on npm.

Getting Started

Check the releases for the latest version.

git clone \
  --single-branch \
  --branch <VERSION> \
  --recurse-submodules \
  https://github.com/input-output-hk/cardano-graphql.git \
  && cd cardano-graphql

Build and Run via Docker Compose

Builds @cardano-graphql/server and starts it along with cardano-node, cardano-db-sync-extended, postgresql, and hasura:

docker-compose up -d --build && docker-compose logs -f

ℹ️ Omit the --build to use a pre-built image from Dockerhub (or locally cached from previous build)

Check Cardano DB sync progress

Use the GraphQL Playground in the browser at http://localhost:3100/graphql:

{ cardanoDbMeta { initialized syncPercentage }}

or via command line:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ cardanoDbMeta { initialized syncPercentage }}"}' \
  http://localhost:3100/graphql

ℹ️ Wait for initialized to be true to ensure the epoch dataset is complete.

Query the full dataset

{ cardano { tip { number slotNo epoch { number } } } }

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 } } } } }

For more information, have a look at the Wiki 📖.

How to install (Linux / Docker)

Docker

See Using Docker.

From Source

See Building.

Documentation