api.md

API

DTOs are described in api.ts.

Warning

Most DTOs may contain BigInts. If there are numbers greater than JavaScript native number can fit (f64), then native JSON decoder throws an error.

You should decode DTOs with a special JSON-decoder that works with BigInts, e.g. json-bigint.

Contents

• Endpoints
  • GET /api/v1
  • Blocks
    • GET /api/v1/blocks
    • GET /api/v1/blocks/{height or hash}
  • Transactions
    • GET /api/v1/transactions
    • GET /api/v1/transactions/{hash}
  • Accounts
    • GET /api/v1/accounts
    • GET /api/v1/accounts/{id}
  • Assets
    • GET /api/v1/assets
    • GET /api/v1/assets/{definition_id}/{account_id}
  • Asset Definitions
    • GET /api/v1/asset-definitions
    • GET /api/v1/asset-definitions/{id}
  • Domains
    • GET /api/v1/domains
    • GET /api/v1/domains/{id}
  • Peers
    • GET /api/v1/peer/peers
    • GET /api/v1/peer/status
  • Roles
    • GET /api/v1/roles
• Id Transformation
• Pagination Query Params

Endpoints

GET /api/v1

• Description: web server health check
• Response: 200 OK

Blocks

• /blocks
• /blocks/{height or hash}

GET /api/v1/blocks

• Query: Pagination
• Response: Paginated<BlockShallow>

GET /api/v1/blocks/{height or hash}

• Description: get the block at the given height or hash

• Params: either height or hash

  Param	Type	Description
  height	int	non-zero number indicating the height of the block
  hash	string	32-byte hash hex of the block

• Response: Block or 404

Transactions

• /transactions
• /transactions/{hash}

GET /api/v1/transactions

• Query: Pagination
• Response: Paginated<Transaction>

GET /api/v1/transactions/{hash}

• Params:

  Param	Type	Description
  hash	string	32-byte hash hex of the transaction

• Response: Transaction or 404

Accounts

• /accounts
• /accounts/{id}

GET /api/v1/accounts

• Query: Pagination
• Response: Paginated<Account>

GET /api/v1/accounts/{id}

• Params:

  Param	Type	Description
  id	string	The id of the account

• Response: Account or 404

See also: Id Transformation

Assets

• /assets
• /assets/{definition_id}/{account_id}

GET /api/v1/assets

• Query: Pagination
• Response: Paginated<Asset>

GET /api/v1/assets/{definition_id}/{account_id}

• Params:

  Param	Type	Description
  definition_id	string	The id of the asset definition
  account_id	string	The id of the account the asset belongs to

• Response: Asset or 404

See also: Id Transformation

Asset Definitions

• /asset-definitions
• /asset-definitions/{id}

GET /api/v1/asset-definitions

• Query:Pagination
• Response: Paginated<AssetDefinition>

GET /api/v1/asset-definitions/{id}

• Params:

  Param	Type	Description
  id	string	The id of the asset definition

• Response: AssetDefinitionWithAccounts or 404

See also: Id Transformation

Domains

• /domains
• /domains/{id}

GET /api/v1/domains

• Query: Pagination
• Response: Paginated<Domain>

GET /api/v1/domains/{id}

• Params:

  Param	Type	Description
  id	string	The id of the domain

• Response: Domain or 404

Peer

• /peer/peers
• /peer/status

GET /api/v1/peer/peers

• Response: Peer[]

GET /api/v1/peer/status

• Response: Status

Roles

GET /api/v1/roles

• Response: Role[]

Id Transformation

IDs in path should be HTML-escaped:

	In DTO	In path
Domain Id	wonderland	wonderland
Account Id	alice@wonderland	alice@wonderland
Asset Definition Id	rose#wonderland	rose%23wonderland

Pagination Query Params

Param	Type	Default	Description
page	number	1	Page number
page_size	number	15	Page size limit