Validator API

Validator API

Use REST APIs to interact directly with the Tableland network of validator nodes.

The Tableland Validator API is organized around REST. You can leverage these APIs to read directly from tables and compose data across them, and make calls to learn information about the node itself. Keep in mind that a node listens to mainnet chains and testnet chains separately such that there are separate Base URLs for each respective environment.

Setup

There are no required prerequisites, but it may be helpful to become familiar with HTTPie and cURL since the examples provided use these. Also, jq is an optional tool to help pipe the output from the API calls to a more human readable, “pretty” format (e.g., curl <url> | jq).

Base URLs

The following base URLs are supported:

  • Testnet chains ⇒ https://testnets.tableland.network/api/v1
  • Mainnet chains ⇒ https://tableland.network/api/v1

Endpoints

The following endpoints are available at the Base URL gateways above:

Mainnets vs. Testnets Gateway

Be sure to use https://tableland.network on mainnets, and https://testnets.tableland.network on testnets.

At the protocol level, the Tableland network is separated such that nodes process and respond to SQL queries relative to each environment. If you were to use the testnets gateway on a mainnet chain / contract, this would lead to issues. The testnets gateway only queries tables that exist on testnet chains, whereas the tableland.network gateway only queries tables that exist on mainnet chains.

Definitions

  • transactionHash ⇒ Resultant on-chain transaction hash corresponding to a table’s creation or a write query.
  • chainId ⇒ Blockchain or L2 solution on which transactions are being sent; available chainId values can be found here.
  • tableId ⇒ The unique identifier assigned to the created table upon the contract minting the table as an ERC721 token.

Synopsis

This general API specification is used to automatically generate clients and backend services; it should be used as the primary source of truth for Validator APIs. This specification is a living document, and as such, may be updated over time. Proposals for the addition of API features and fixes may be submitted by the Tableland community over time. These proposals will be evaluated for technical feasibility, utility to the community, and longer-term sustainability.

In Tableland, Validators are the execution unit/actors of the protocol. They have the following responsibilities:

  • Listen to on-chain events to materialize Tableland-compliant SQL queries in a database engine (currently, SQLite by default).
  • Serve read-queries (e.g: SELECT * FROM foo_69_1) to the external world.
  • Serve state queries (e.g. list tables, get receipts, etc) to the external world.

Base URLs

query

See the Query Formatting section for how to transform the response, such as making it ERC721 compliant.

Query the network

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/query?statement=select%20%2A%20from%20healthbot_80001_1 \
  -H 'Accept: application/json'

GET /query

Returns the results of a SQL read query against the Tableland network

Parameters

Name
In
Type
Required
Description
statement
query
string
true
The SQL read query statement
format
query
string
false
The requested response format:
extract
query
boolean
false
Whether to extract the JSON object from the single property of the surrounding JSON object.
unwrap
query
boolean
false
Whether to unwrap the returned JSON objects from their surrounding array.

Detailed descriptions

format: The requested response format:

  • objects - Returns the query results as a JSON array of JSON objects.
  • table - Return the query results as a JSON object with columns and rows properties.

Enumerated Values

Parameter
Value
format
objects
format
table

Example responses

  • 200 Response
{}

Responses

Status
Meaning
Description
Schema
200
Successful operation
Inline
400
Invalid query/statement value
None
404
Row Not Found
None
429
Too Many Requests
None

Response Schema

This operation does not require authentication

receipt

Get information about transaction progress

Get transaction status

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/receipt/{chainId}/{transactionHash} \
  -H 'Accept: application/json'

GET /receipt/{chainId}/{transactionHash}

Returns the status of a given transaction receipt by hash

Parameters

Name
In
Type
Required
Description
chainId
path
integer(int32)
true
The parent chain to target
transactionHash
path
string
true
The transaction hash to request

Example responses

  • 200 Response
{
  "table_id": "1",
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80001,
  "error": "The query statement is invalid",
  "error_event_idx": 1
}

Responses

Status
Meaning
Description
Schema
200
successful operation
TransactionReceipt
400
Invalid chain identifier or transaction hash format
None
404
No transaction receipt found with the provided hash
None
429
Too Many Requests
None

This operation does not require authentication

tables

Access to table information

Get table information

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/tables/{chainId}/{tableId} \
  -H 'Accept: application/json'

GET /tables/{chainId}/{tableId}

Returns information about a single table, including schema information

Parameters

Name
In
Type
Required
Description
chainId
path
integer(int32)
true
The parent chain to target
tableId
path
string
true
Table identifier

Example responses

  • 200 Response
{
  "name": "healthbot_5_1",
  "external_url": "https://testnet.tableland.network/tables/healthbot_5_1",
  "animation_url": "https://render.tableland.xyz/anim/?chain=1&id=1",
  "image": "https://render.tableland.xyz/healthbot_5_1",
  "attributes": {
    "display_type": "date",
    "trait_type": "created",
    "value": 1657113720
  },
  "schema": {
    "columns": [
      {
        "name": "id",
        "type": "integer",
        "constraints": [
          "NOT NULL",
          "PRIMARY KEY",
          "UNIQUE"
        ]
      }
    ],
    "table_constraints": [
      "PRIMARY KEY (id)"
    ]
  }
}

Responses

Status
Meaning
Description
Schema
200
successful operation
400
Invalid chain or table identifier
None
404
Table Not Found
None
429
Too Many Requests
None
500
Internal Server Error
None

This operation does not require authentication

health

Get health status

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/health

GET /health

Returns OK if the validator considers itself healthy.

Responses

Status
Meaning
Description
Schema
200
The validator is healthy.
None

This operation does not require authentication

version

Get version information

Example

# You can also use wget
curl -X GET https://testnets.tableland.network/api/v1/version \
  -H 'Accept: application/json'

GET /version

Returns version information about the validator daemon.

Example responses

  • 200 Response
{
  "version": 0,
  "git_commit": "79688910d4689dcc0991a0d8eb9d988200586d8f",
  "git_branch": "foo/experimentalfeature",
  "git_state": "dirty",
  "git_summary": "v1.2.3_dirty",
  "build_date": "2022-11-29T16:28:04Z",
  "binary_version": "v1.0.1"
}

Responses

Status
Meaning
Description
Schema
200
successful operation
VersionInfo

This operation does not require authentication

Schemas

Table

{
  "name": "healthbot_5_1",
  "external_url": "https://testnet.tableland.network/tables/healthbot_5_1",
  "animation_url": "https://render.tableland.xyz/anim/?chain=1&id=1",
  "image": "https://render.tableland.xyz/healthbot_5_1",
  "attributes": {
    "display_type": "date",
    "trait_type": "created",
    "value": 1657113720
  },
  "schema": {
    "columns": [
      {
        "name": "id",
        "type": "integer",
        "constraints": [
          "NOT NULL",
          "PRIMARY KEY",
          "UNIQUE"
        ]
      }
    ],
    "table_constraints": [
      "PRIMARY KEY (id)"
    ]
  }
}

Properties

Name
Type
Required
Restrictions
Description
name
string
false
none
none
external_url
string
false
none
none
animation_url
string
false
none
none
image
string
false
none
none
attributes
[object]
false
none
none
» display_type
string
false
none
The display type for marketplaces
» trait_type
string
false
none
The trait type for marketplaces
» value
object
false
none
The value of the property

oneOf

Name
Type
Required
Restrictions
Description
»» anonymous
string
false
none
none

xor

Name
Type
Required
Restrictions
Description
»» anonymous
number
false
none
none

xor

Name
Type
Required
Restrictions
Description
»» anonymous
integer
false
none
none

xor

Name
Type
Required
Restrictions
Description
»» anonymous
boolean
false
none
none

xor

Name
Type
Required
Restrictions
Description
»» anonymous
object
false
none
none

continued

Name
Type
Required
Restrictions
Description
schema
Schema
false
none
none

TransactionReceipt

{
  "table_id": "1",
  "transaction_hash": "0x02f319429b8a7be1cbb492f0bfbf740d2472232a2edadde7df7c16c0b61aa78b",
  "block_number": 27055540,
  "chain_id": 80001,
  "error": "The query statement is invalid",
  "error_event_idx": 1
}

Properties

Name
Type
Required
Restrictions
Description
table_id
string
false
none
none
transaction_hash
string
false
none
none
block_number
integer(int64)
false
none
none
chain_id
integer(int32)
false
none
none
error
string
false
none
none
error_event_idx
integer(int32)
false
none
none

Schema

{
  "columns": [
    {
      "name": "id",
      "type": "integer",
      "constraints": [
        "NOT NULL",
        "PRIMARY KEY",
        "UNIQUE"
      ]
    }
  ],
  "table_constraints": [
    "PRIMARY KEY (id)"
  ]
}

Properties

Name
Type
Required
Restrictions
Description
columns
[Column]
false
none
none
table_constraints
[string]
false
none
none

Column

{
  "name": "id",
  "type": "integer",
  "constraints": [
    "NOT NULL",
    "PRIMARY KEY",
    "UNIQUE"
  ]
}

Properties

Name
Type
Required
Restrictions
Description
name
string
false
none
none
type
string
false
none
none
constraints
[string]
false
none
none

VersionInfo

{
  "version": 0,
  "git_commit": "79688910d4689dcc0991a0d8eb9d988200586d8f",
  "git_branch": "foo/experimentalfeature",
  "git_state": "dirty",
  "git_summary": "v1.2.3_dirty",
  "build_date": "2022-11-29T16:28:04Z",
  "binary_version": "v1.0.1"
}

Properties

Name
Type
Required
Restrictions
Description
version
integer(int32)
false
none
none
git_commit
string
false
none
none
git_branch
string
false
none
none
git_state
string
false
none
none
git_summary
string
false
none
none
build_date
string
false
none
none
binary_version
string
false
none
none

Query Formatting

Transform the /query endpoint response to a specific format (it only applies to this endpoint).

Adding Path Parameters

To leverage the query response formatting, add the options specified below as a query parameter. Namely, after using /query?, specify a parameter and its value using the syntax {parameter}={value} and append or prepend an ampersand &.

ERC721 Compliance

For example, a query used composing ERC721 compliant metadata (e.g., leveraging usage of json_object) should include unwrap=true&extract=true somewhere in the query string, either at the beginning or the end:

  • /query?unwrap=true&extract=true&s={readStatement}
  • /query?s={readStatement}&unwrap=true&extract=true

Parameters

output

Specify the JSON response’s shape and style.

objects (default) A top-level array that contains objects, where each object is a key-value pair of column name to row value. Note the word is plural, not singular.

table A top-level object that contains the keys columns and rows. The columns is an array of column objects, and the rows field is an array of row arrays.

unwrap

Instead of putting objects in a JSON array, unwrap them and use new line delimited JSON Lines. Defaults to false

Only applies to output=objects.

extract

Whether or not to extract single column result values and use those as the results in the response. Defaults to false.

Only applies to output=objects.

json_strings

Whether or not to leave JSON strings as strings in query results or transform them to actual JSON data. Defaults to false.

Basic Examples

The following examples leverage the table rest_api_80001_2580. Each example, unless otherwise specified, is using the default values noted above.

output

objects

output=objects
[
    {
        "id": 0,
        "name": "Bobby Tables"
    }
]

table

output=table
{
  "columns": [
    {
      "name": "id"
    },
    {
      "name": "name"
    }
  ],
  "rows": [
    [
      0,
      "Bobby Tables"
    ]
  ]
}

unwrap

Only works with output=objects.

false

output=objects&unwrap=false
[
  {
    "id": 0,
    "name": "Bobby Tables"
  }
]

true

output=objects&unwrap=false
{
  "id": 0,
  "name": "Bobby Tables"
}

extract

Assuming the default, unwrap=false.

false

Only works with output=objects, and it’s only valid for a single column response (i.e., SELECT a single column). Below, we’re only selecting the id column from our table.

output=objects&extract=false
[
  {
    "id": 0
  }
]

true

output=objects&extract=true
[
  0
]

When using unwrap=true.

false

output=objects&unwrap=true&extract=false
{
  "id": 0
}

true

output=objects&unwrap=true&extract=true
0

Interactive Demo

Test out the Validator API yourself!

← Previous