About
Protocol
Walkthroughs
Integrations
Intro to NFT Metadata
Tutorials
Smart Contracts
Concepts
Playbooks
Learn
REST API (Legacy)
Requests for table information and running SQL read queries.
There are a number of REST APIs that allow developers to retrieve all of their owned tables, tables owned by a specific address, basic table information, and even raw SQL queries in the URL itself. Plus, leverage query formatting for tailoring the API response data, such as for ERC721 compliance.
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
).
Settings
Since all of the REST APIs are purely GET
requests, there is no Authorization nor Content-Type header required; that is, reads are not a on-chain operation and are unauthenticated for those using the Tableland gateway. All responses have a Content-Type
of type application/json
.
Endpoints
The base URL is the following:
- Testnets ⇒
https://testnets.tableland.network
- Mainnets ⇒
https://tableland.network
And following endpoints are available via gateway(s):
/chain/{chainId}/tables/controller/{address}
/chain/{chainId}/tables/{id}
/chain/{chainId}/tables/structure/{hash}
/query?s={readStatement}
/schema/{tableName}
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
- Structure hash ⇒ Hash generated upon table creation that describes uniquely describes a table schema (i.e., identical schemas have equivalent structure hashes)
- Transaction ⇒ Instructions corresponding an on-chain activity, represented as a hash
- Controller ⇒ The owner of a table, note that this is not the same as a controller contract.
- ChainId ⇒ Blockchain or L2 solution on which transactions are being sent; available chainId options can be found here.
Examples Format
The provided examples leverage a table named rest_api_80001_2580
, deployed on the Polygon Mumbai testnet. It has a schema of id int, name text
.
REST API Reference
/chain/{chainId}/tables/controller/{address}
Get all tables owned by an address for a given chain.
Path Parameters
chainId: <int>
⇒ The chainId corresponding to the chain that tables are deployed onaddress: <string>
⇒ Address to be queried against for a list of owned tables
Request
N/A — no request body should be passed
Responses
200
(success)
<array>
⇒ Array of objects, each describing a single table<object>
(optional) ⇒ If no tables are controlled by the passed address, no objects are returnedcontroller: <string>
⇒ Table owner’s address, matching the address passed as a parametername: <string>
⇒ Table name in the format{prefix}_{chainId}_{tableId}
structure: <string>
⇒ Structure hash of the table’s schemacreated_at: <string>
⇒ Time at which each validator created the table within its local store
400
(bad request)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
500
(internal sever error)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- Failed to fetch tables ⇒ There was an issue with finding the requested chainId (i.e., chainId that is not supported)
Note: if an invalid address is passed, the status code will still be a 200
but returns an empty array
Examples
Request (using curl):
curl https://testnets.tableland.network/chain/80001/tables/controller/0x4D5286d81317E284Cd377cB98b478552Bbe641ae
Request (using httpie):
http --print=b https://testnets.tableland.network/chain/80001/tables/controller/0x4D5286d81317E284Cd377cB98b478552Bbe641ae
Responses (200
success):
[
{
"controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
"name": "rest_api_80001_2580",
"structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
}
]
/chain/{chainID}/tables/{tableId}
Get the ERC-721 compliant metadata associated with a table for a given chain
Path Parameters
chainId: <int>
⇒ The chainId corresponding to the chain that tables are deployed ontableId: <int>
⇒ Unique identifier for the table on the corresponding chain (i.e., the tableId from{prefix}_{chainId}_{tableId}
)
Request
N/A — no request body should be passed
Responses
200
(success)
<object>
⇒ ERC-721 compliant metadata about the tablename: <string>
⇒ Name of the table in the format{prefix}_{chainId}_{tableId}
external_url: <string>
⇒ External URL to the table, which matches with the endpoint itselfimage: <string>
⇒ A URL leading to a default Tableland image (the same for all tables)attributes: <array>
⇒ Array of metadata attributesdisplay_type: <string>
⇒ Defined as “date”trait_type: <string>
⇒ Defined as “created”value: <int>
⇒ A unix timestamp (seconds) value
400
(bad request)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
- Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)
500
(internal sever error)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)
Examples
Request (using curl):
curl https://testnets.tableland.network/chain/80001/tables/2580
Request (using httpie)
http --print=b https://testnets.tableland.network/chain/80001/tables/2580
Response (200
success):
{
"name": "rest_api_80001_2580",
"external_url": "https://testnets.tableland.network/chain/80001/tables/2580",
"image": "https://render.tableland.xyz/80001/2580",
"attributes": [
{
"display_type": "date",
"trait_type": "created",
"value": 1663808196
}
]
}
/chain/{chainId}/tables/structure/{hash}
Get all tables with a matching table structure on a specific chain.
Path Parameters
chainId: <int>
⇒ The chainId corresponding to the chain that tables are deployed onhash: <string>
⇒ Structure hash of a table
Request
N/A — no request body should be passed
Responses
200
(success)
<array>
⇒ Array of objects, each describing a single table<object>
(optional) ⇒ If no tables are controlled by the passed address, no objects are returnedcontroller: <string>
⇒ Table owner’s address, matching the address passed as a parametername: <string>
⇒ Table name in the format{prefix}_{chainId}_{tableId}
structure: <string>
⇒ Structure hash of the table’s schema
400
(bad request)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
500
(internal sever error)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- Failed to fetch tables ⇒ There was an issue with finding the requested chainId (i.e., chainId that is not supported)
Note: if an invalid address is passed, the status code will still be a 200
but return an empty array
Examples
Request (using curl):
curl https://testnets.tableland.network/chain/80001/tables/structure/7d5cd636b3cb913155fe97a54af38383c2a7a94c98369616bdfe6409558cc57a
Request (using httpie):
http --print=b https://testnets.tableland.network/chain/80001/tables/structure/7d5cd636b3cb913155fe97a54af38383c2a7a94c98369616bdfe6409558cc57a
Responses (200
success):
[
{
"controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
"name": "rest_api_80001_2580",
"structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
},
{
"controller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
"name": "_80001_2151",
"structure": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
}
]
/query?s={readStatement}
Get the response from a read query, set to the value of the s
query string parameter.
For transforming the /query
response, see the query formatting section below.
Path Parameters
readStatement: <string>
⇒ A URL encoded read query (see the examples for context)
Request
N/A — no request body should be passed
Responses
200
(success)
<object>
⇒ Object containing all results matching the read query statementcolumns: <array>
⇒ Array of objects, each describing a corresponding table column<object>
⇒ Object containing information about a single columnname: <string>
⇒ The name of the columnrows: <array>
⇒ Array of arrays, each describing the table columns<array>
⇒ Array of row values, each separated by a comma and corresponding to the order of the objects incolumns
400
(bad request)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
- Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)
500
(internal sever error)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)
Examples
For this example, take the statement SELECT * FROM rest_api_5_85
, which translates to a URL encoded string: SELECT%20*%20FROM%20rest_api_5_85
. Note that it must be further sanitized for the sake of using curl
or httpie
by also escaping characters. However, for demonstration purposes, it is possible to simply paste this query into most modern browsers, like so:
https://testnets.tableland.network/query?s=SELECT * FROM rest_api_80001_2580
# most browsers will automtically encode this as:
https://testnets.tableland.network/query?s=SELECT%20*%20FROM%20rest_api_80001_2580
Request (using curl):
curl https://testnets.tableland.network/query\?s\=SELECT%20\*%20FROM%20rest_api_80001_2580
Request (using httpie)
http --print=b https://testnets.tableland.network/query\?s\=select%20\*%20FROM%20rest_api_80001_2580
Responses (200
success):
[
{
"id": 0,
"name": "Bobby Tables"
}
]
/schema/{tableName}
Get the schema and constraints for a table.
Path Parameters
tableName: <string>
⇒ The tableName in the format{prefix}_{chainId}_{tableId}
Request
N/A — no request body should be passed
Responses
200
(success)
<object>
⇒ Object containing all results matching the read query statementcolumns: <array>
⇒ Array of objects, each describing a corresponding table column<object>
⇒ Object containing information about a single columnname: <string>
⇒ The name of the columntype: <integer>
⇒ The SQL data type, defined in the SQL Specificationconstraints: <array>
⇒ Array of column constraints<string>
⇒ Column constraints, such asPRIMARY KEY
table_contraints: <array>
⇒ Array constraints on the table as a whole<string>
⇒ The table constraint
400
(bad request)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- No chain id in path ⇒ The passed chainId was an invalid format (i.e., wrong type)
- Invalid id format ⇒ The passed id was an invalid format (e.g., wrong type)
500
(internal sever error)
<object>
⇒ Object containing the error messagemessage: <string>
⇒ The error message- Failed to fetch metadata ⇒ The metadata for the given id could not be found (i.e., nonexistent table id or a chainId that is not supported)
Examples
Request (using curl):
curl https://testnets.tableland.network/schema/rest_api_80001_2580
Request (using httpie)
http --print=b https://testnets.tableland.network/schema/rest_api_80001_2580
Responses (200
success):
{
"columns": [
{
"name": "id",
"type": "int",
"constraints": []
},
{
"name": "name",
"type": "text",
"constraints": []
}
],
"table_constraints": []
}
Query Formatting
Transform the /query
endpoint response to a specific format.
Only applies to the /query
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
← Previous
Next →
On this page
- REST API (Legacy)
- Setup
- Settings
- Endpoints
- Mainnets vs. Testnets Gateway
- Definitions
- Examples Format
- REST API Reference
- /chain/{chainId}/tables/controller/{address}
- Path Parameters
- Request
- Responses
- Examples
- /chain/{chainID}/tables/{tableId}
- Path Parameters
- Request
- Responses
- Examples
- /chain/{chainId}/tables/structure/{hash}
- Path Parameters
- Request
- Responses
- Examples
- /query?s={readStatement}
- Path Parameters
- Request
- Responses
- Examples
- /schema/{tableName}
- Path Parameters
- Request
- Responses
- Examples
- Query Formatting
- Adding Path Parameters
- ERC721 Compliance
- Parameters
- output
- unwrap
- extract
- json_strings
- Basic Examples
- output
- unwrap
- extract