docs/developers/aquarius-rest-api.md

Aquarius REST API

The universal Aquarius Endpoint is https://v4.aquarius.oceanprotocol.com.

Assets

Get /api/aquarius/assets/ddo/<did>

• Description

  Get DDO of a particular asset.

• Parameters

  name	description	type	in	required
  did	DID of the asset	string	path	true

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/ddo/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6'
  

• Responses

  • 200
    • content-type: json
    • description: On successful operation returns DDO information.
  • 404

    • content-type: json

    • description: This asset DID is not in ES.

    • response body:

      {
          "error": "Asset DID <did> not found in Elasticsearch."
      }
      

GET /api/aquarius/assets/metadata/<did>

• Description

  Get metadata of a particular asset.

• Parameters

  name	description	type	in	required
  did	DID of the asset	string	path	true

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/metadata/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6'
  

• Responses

  • 200
    • content-type: json
    • description: successful operation.
  • 404

    • content-type: json

    • description: This asset DID is not in ES.

    • response body:

      {
          "error": "Error encountered while retrieving metadata: NotFoundError(404, '{\"_index\":\"aquarius\",\"_type\":\"_doc\",\"_id\":\"<did>\",\"found\":false}')."
      }
      

POST /api/aquarius/assets/names

• Description

  Get names of assets as specified in the payload.

• Parameters

  name	description	type	in	required
  didList	list of asset DIDs	list	body	true

• Example

  curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/names' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "didList" : ["did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6"]
  }'
  

• Responses

  • 200

    • content-type: json

    • description: successful operation.

    • response body:

      {"did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6": "Ocean CEX Aggregator: OHLC history for OCEAN/USDT "}
      

  • 400

    • content-type: json

    • description: This asset DID is not in ES.

    • response body:

      {
      "error": "The requested didList can not be empty."
      }
      

POST /api/aquarius/assets/query

• Description

  Run a native ES query. Body must be a valid json object.

• Example

  curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "query": {
          "match_all": {}
      }
  }'
  

• Responses

  • 200
    • content-type: json
  • 500
    • description: elasticsearch exception

POST /api/aquarius/assets/ddo/validate

• Description

  Validate DDO content. Cosumes application/octet-stream

• Example

  curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/aquarius/assets/ddo/validate' \
  --header 'Content-Type: application/json' \
  --data-raw '<json_body>'
  

• Valid body

      {
          "@context": ["https://w3id.org/did/v1"],
          "id": "did:op:56c3d0ac76c02cc5cec98993be2b23c8a681800c08f2ff77d40c895907517280",
          "version": "4.1.0",
          "chainId": 1337,
          "nftAddress": "0xabc",
          "metadata": {
              "created": "2000-10-31T01:30:00.000-05:00Z",
              "updated": "2000-10-31T01:30:00.000-05:00",
              "name": "Ocean protocol white paper",
              "type": "dataset",
              "description": "Ocean protocol white paper -- description",
              "author": "Ocean Protocol Foundation Ltd.",
              "license": "CC-BY",
              "contentLanguage": "en-US",
              "tags": ["white-papers"],
              "additionalInformation": {"test-key": "test-value"},
              "links": [
                  "http://data.ceda.ac.uk/badc/ukcp09/data/gridded-land-obs/gridded-land-obs-daily/",
                  "http://data.ceda.ac.uk/badc/ukcp09/data/gridded-land-obs/gridded-land-obs-averages-25km/",
                  "http://data.ceda.ac.uk/badc/ukcp09/"
              ]
          },
          "services": [
              {
                  "id": "test",
                  "type": "access",
                  "datatokenAddress": "0xC7EC1970B09224B317c52d92f37F5e1E4fF6B687",
                  "name": "Download service",
                  "description": "Download service",
                  "serviceEndpoint": "http://172.15.0.4:8030/",
                  "timeout": 0,
                  "files": "encryptedFiles"
              }
          ]
      }
  

• Responses:

  • 200
    • description: successfully request.
  • 400
    • description: Invalid DDO format
  • 500
    • description: Error

POST /api/aquarius/assets/triggerCaching

• Description

  Manually triggers DDO caching based on a transacionId containing either MetadataCreated or MetadataUpdated event(s).

• Parameters

  name	description	type	in	required
  transactionId	DID of the asset	string	path	true
  logIndex	custom log index for the transaction	int	path	false

• Example

  curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/triggerCaching' \
  --header 'Content-Type: application/json' \
  --data-raw '<json_body>'
  

• Valid body

      {
          "transactionId": "0x945596edf2a26d127514a78ed94fea86b199e68e9bed8b6f6d6c8bb24e451f27",
          "logIndex": 0
      }
  

• Responses:

  • 200
    • description: triggering successful, updated asset returned
  • 400
    • description: request issues: either log index not found, or neither of MetadataCreated, MetadataUpdated found in tx log
  • 500
    • description: Error

Chains

GET /api/aquarius/chains/list

• Description

  Get chains list

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/chains/list'
  

• Response

  • 200

    • Description: Successful request

    • Body

      {   "246": true, "3": true, "137": true,
          "2021000": true, "4": true, "1": true,
          "56": true, "80001": true, "1287": true
      }
      

GET /api/aquarius/chains/status/{chain_id}

• Description

  Get index status for a specific chain_id

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/chains/status/137'
  

• Response

  • 200

    • Description: Successful request

    • Body

      {"last_block": 25198729}
      

Others

GET /

• Description

  Get version, plugin, and software information.

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/'
  

• Response

  • 200

    • Description: Successful request

    • Body

      {
          "plugin": "elasticsearch",
          "software": "Aquarius",
          "version": "4.2.0"
      }
      

GET /health

• Description

  Get health status

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/health'
  

• Response

  • 200

    • Description: Successful request

    • Body

      Elasticsearch connected
      

GET /spec

• Description

  Get swagger spec

• Example

  curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/spec'
  

• Response

  • 200
    • Description: Successful request

Postman documentation

Click here to explore the documentation and more examples in postman.