diff --git a/network-rfc/11_portal_api.md b/network-rfc/11_portal_api.md index 0b50848..bf27a07 100644 --- a/network-rfc/11_portal_api.md +++ b/network-rfc/11_portal_api.md @@ -32,6 +32,8 @@ Response example: Lists the existing datasets as a JSON array. See [`/metadata` endpoint](#get-datasetsdatasetmetadata) for the field description. +Supports `expand[]` query parameter to include additional metadata fields (see [Additional metadata fields](#additional-metadata-fields-experimental)). + Response example: ```json [ @@ -49,7 +51,7 @@ Response example: ] ``` -### `GET /datasets//metadata` +### `GET /datasets/` Responds with the information describing the dataset as a JSON object. Contains at least the following fields: - `dataset` — the default name used to reference this dataset. @@ -57,6 +59,8 @@ Responds with the information describing the dataset as a JSON object. Contains - `real_time`, indicating whether the portal has real-time data for this dataset. - `start_block` — the block number of the first known block in the dataset. The client should not request any blocks below this number. +Supports `expand[]` query parameter to include additional metadata fields (see [Additional metadata fields](#additional-metadata-fields-experimental)). + Response example: ```json { @@ -67,6 +71,33 @@ Response example: } ``` +#### Additional metadata fields (EXPERIMENTAL) + +Both `/datasets` and `/datasets/` endpoints support the `expand[]` query parameter, which controls the inclusion of additional metadata fields. + +- By default (no `expand[]` parameters), only the base fields (`dataset`, `aliases`, `real_time`, `start_block`) are returned. +- Each `expand[]=` parameter requests a specific top-level metadata field to be included in the response. Multiple fields can be requested by repeating the parameter. + +Example request: `GET /datasets/?expand[]=metadata` + +Example response: +```json +{ + "dataset": "ethereum-mainnet", + "aliases": [], + "real_time": true, + "metadata": { + "display_name": "Ethereum", + "logo_url": "https://cdn.subsquid.io/img/networks/ethereum.svg", + "type": "testnet", + "kind": "evm", + "evm": { + "chain_id": 1 + } + } +} +``` + ### `GET /datasets//state` Responds with a summary of stored block ranges for the given dataset. May be used for displaying network status in the UI.\ @@ -247,3 +278,7 @@ Same as `/datasets//finalized-stream/height` ### `GET /datasets//query/` Sends the query to the worker. The query is passed in the request body. + +### `GET /datasets//metadata` + +Same as `/datasets/`