DataGate API

Intro

DataGate API uses POST methods. Endpoints receive and return JSON documents.

Data models of API requests and responses are well annotated. In the API portal you can see description & types of the fields and example requests / responses.

Requests

API endpoints receive JSON docs with the parameters of the request. Every endpoint provides different parameters to select the data:

• Endpoints allow to select records based on data from receipts of blockchain entities, such as block index or transaction hash.

• Also endpoints allow to select records based on the particular on-chain values. For example, you can select all token transfers of the amount bigger than 100;

You can construct complex requests over blockchain data using comparison operators $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin and logical operators $and, $not, $nor, $or. So you can precisely select subset of blockchain data. The overall syntax of requests is almost identical to one of MongoDB requests. Please see the examples on Datagate API portal.

API performs strict validation of request' JSON docs. In case of any error you will receive 422 HTTP error code with description of the issue.

Responses

API endpoints provide JSON docs as the result of request. It always has two top level keys:

• data contains the result of request execution.

• metadata contains auxiliary information:

  • metadata.request_context helps maintain consistency of the fetched data. See Data consistency;

  • metadata.blockchain_head contains the last finalised block. So that you always know the current blockchain tip;

  • metadata.pagination contains information about the next data page. See below Pagination;

Support of keyless addresses

Keyless addresses play the important role in TRAIT platform. The DataGate provides a good support of such address.

API requests supports filtering by blockchain addresses. When you make a request, you can specify addresses with IDs of keyless addresses. Examples:

• field origin shall match any keyless transactional address controlled by the AppAgent 100: { "origin": { "app_agent_id": 100, "address_type": "transactional" } }

• field origin shall match any keyless transactional address from the range [1000, 1100] controlled by the AppAgent 100: { "origin": { "app_agent_id": 100, "ta_id": {"min": 1000, "max": 1100} } }

When you receive API response all address fields contain detailed information about the address:

{
    "origin": {
        "address": "ttoRAiFEXDNLZ531FVRnDZmGTfW5Yamt6d8Ce3A8PK6CWJD3b",
        "account_id": "0x6400000002f906000033e4dc5903c8ef6355c8feb9b7cf744197feaf5c62f535",
        "address_type": "transactional",
        "app_agent_id": 100,
        "ta_id": 1785,
        "address_name": null
    }
}

See the DataGate API portal for more examples.

Pagination

Response of API requests could contain a lot of records. Such responses are automatically split into data pages.

The response JSON will contain the object metadata.pagination :

{ "current_page": 0, "next_page_id": "6e582484-1c78-4dcd-984a-2037cfe48084" }

To get the next data page you need to make the second request to the same endpoint and provide ID of the next data page:

{ "page_id": "6e582484-1c78-4dcd-984a-2037cfe48084" }