Skip to main content
Version: Firesquid

GraphQL API Server

The squid data can be presented with a GraphQL API. The OpenReader server takes the schema file as an input argument and starts a GraphQL API serving OpenCRUD read queries for the entities defined in the schema.

To start the API server:

npx make serve

The API server listens at port defined by GQL_PORT (default to 4350). The database connection is configured with the env variables DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT.

The API server is automatically started when the squid is deployed to the Aquarium.

Supported Queries​

The details of the supported OpenReader queries can be found in a separate section Query a Squid. Here is a brief overview of the queries generated by OpenReader for each entity defined in the schema file:

  • the squid last processed block is available with squidStatus { height } query
  • a "get one by ID" query with the name {entityName}ById
  • a "get one" query for @unique fields, with the name {entityName}ByUniqueInput
  • a lookup query with the name {entityName}s. It supports filtering on each entity field with a where parameter, predicate compositions with AND and OR and limiting with the offset and limit parameters.
  • a GraphQL Cursor pagination query with the name {entityName}sConnection

Nested queries are supported out-of-the-box for entity relations:

  • for the one side of a relation, where supports filtering on any field of the related entity
  • for the many side of a relation, where supports filters XXX_some, XXX_every and XXX_none that match only if at least one (resp. each and none) of the related entities match the predicate.

Union and typed JSON types are mapped into GraphQL Union Types with a proper type resolution with __typename.

Built-in custom scalars​

The OpenReader GraphQL API defines the following custom scalars in the GraphQL to present the corresponding entity fields:

  • DateTime: DateTime fields in the schema are presented in the ISO format
  • Bytes: Bytes fields are presented as hex-encoded strings prefixed with 0x
  • BigInt: BigInt fields are presented as strings