From 1f1547960c1af0b4f0321cff98917746741e2fbf Mon Sep 17 00:00:00 2001 From: Jamie Hewitt Date: Mon, 22 May 2023 07:37:40 +0000 Subject: [PATCH] GITBOOK-204: change request with no subject merged in GitBook --- developers/apis/aquarius.md | 365 +++++++++++++++++++++--------------- 1 file changed, 209 insertions(+), 156 deletions(-) diff --git a/developers/apis/aquarius.md b/developers/apis/aquarius.md index cee6a6cc..63424efc 100644 --- a/developers/apis/aquarius.md +++ b/developers/apis/aquarius.md @@ -1,4 +1,4 @@ -# Aquarius REST API +# Aquarius The universal Aquarius Endpoint is [`https://v4.aquarius.oceanprotocol.com`](https://v4.aquarius.oceanprotocol.com). @@ -6,184 +6,233 @@ The universal Aquarius Endpoint is [`https://v4.aquarius.oceanprotocol.com`](htt ### **Get** `/api/aquarius/assets/ddo/` -* Description +#### Description - Get DDO of a particular asset. -* Parameters +Get DDO of a particular asset. - | name | description | type | in | required | - | ----- | ---------------- | ------ | ---- | -------- | - | `did` | DID of the asset | string | path | true | -* Example +#### Parameters + +| name | description | type | in | required | +| ----- | ---------------- | ------ | ---- | -------- | +| `did` | DID of the asset | string | path | true | + +#### Curl Example + +``` +curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/ddo/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6' +``` + +#### Javascript Example + +```runkit nodeVersion="18.x.x" +const axios = require('axios') +const did = 'did:op:ce3f161fb98c64a2ded37fd34e25f28343f2c88d0c8205242df9c621770d4b3b' +const response = await axios(`https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/ddo/${did}`) +console.log(response.status) +console.log(response.data.nftAddress) +console.log(response.data.metadata.name) +console.log(response.data.metadata.description) + +``` + +#### 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: - ```bash - 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 not found in Elasticsearch." - } - ``` + { + "error": "Asset DID not found in Elasticsearch." + } + ``` ### **GET** `/api/aquarius/assets/metadata/` -* Description +#### Description - Get metadata of a particular asset. -* Parameters +Get metadata of a particular asset. - | name | description | type | in | required | - | ----- | ---------------- | ------ | ---- | -------- | - | `did` | DID of the asset | string | path | true | -* Example +#### Parameters + +| name | description | type | in | required | +| ----- | ---------------- | ------ | ---- | -------- | +| `did` | DID of the asset | string | path | true | + +#### Example + +```bash +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: - ```bash - 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\":\"\",\"found\":false}')." - } - ``` + { + "error": "Error encountered while retrieving metadata: NotFoundError(404, '{\"_index\":\"aquarius\",\"_type\":\"_doc\",\"_id\":\"\",\"found\":false}')." + } + ``` ### **POST** `/api/aquarius/assets/names` -* Description +#### Description - Get names of assets as specified in the payload. -* Parameters +Get names of assets as specified in the payload. - | name | description | type | in | required | - | --------- | ------------------ | ---- | ---- | -------- | - | `didList` | list of asset DIDs | list | body | true | -* Example +#### Parameters + +| name | description | type | in | required | +| --------- | ------------------ | ---- | ---- | -------- | +| `didList` | list of asset DIDs | list | body | true | + +#### Example + +```bash +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: - ```bash - 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 "} + ``` - ``` - {"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: +`400` - ``` - { - "error": "The requested didList can not be empty." - } - ``` +* 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 +#### **Description** - Run a native ES query. Body must be a valid json object. -* Example +Run a native ES query. Body must be a valid json object. - ```bash - 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 +#### Example + +```bash +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 +#### Description - Validate DDO content. Cosumes `application/octet-stream` -* Example +Validate DDO content. Cosumes `application/octet-stream` - ```bash - 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 '' - ``` -* Valid body +#### Example - ``` - { - "@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" - } +```bash +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 '' +``` + +#### 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/" ] - } - ``` -* Responses: - * 200 - * description: successfully request. - * 400 - * description: Invalid DDO format - * 500 - * description: Error + }, + "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` + +Successfull request. + +`400` + +Invalid DDO format + +`500` + +Error ### **POST** `/api/aquarius/assets/triggerCaching` @@ -308,17 +357,21 @@ The universal Aquarius Endpoint is [`https://v4.aquarius.oceanprotocol.com`](htt ### **GET** /spec -* Description +#### Description - Get swagger spec -* Example +Get swagger spec - ```bash - curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/spec' - ``` -* Response - * 200 - * Description: Successful request +#### Example + +```bash +curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/spec' +``` + +#### Response + +`200` + +Successful request ### Postman documentation