GitBook: [#6] Create API references section
This commit is contained in:
Akshay Patel
gitbook-bot
parent
23c28cbe01
commit
1a3818d983
17
README.md
17
README.md
|
|
@ -1,8 +1,9 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Ocean Protocol - Tools for the Web3 Data Economy
|
||||
---
|
||||
|
||||
# Orientation
|
||||
|
||||
In Ocean Protocol, each asset gets its own ERC721 **data NFT** and one(or more) ERC20 **datatokens**. This enables data wallets, data exchanges, and data co-ops by directly leveraging crypto wallets, exchanges, and more.
|
||||
|
||||
OCEAN token is used for staking, and more. [Here](https://oceanprotocol.com/token) are details.
|
||||
|
|
@ -13,13 +14,9 @@ Ocean Protocol provides tools for developers to _build data markets_, and to _ma
|
|||
|
||||
**Manage datatokens and data NFTs for use in DeFi.** Use Ocean [JavaScript](https://github.com/oceanprotocol/ocean.js) or [Python](https://github.com/oceanprotocol/ocean.py) drivers to manage data NFTs and datatokens:
|
||||
|
||||
- _Publish and access data services:_ downloadable files or compute-to-data. Use Ocean to deploy a new [ERC721](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md) and [ERC20](https://github.com/ethereum/EIPs/blob/7f4f0377730f5fc266824084188cc17cf246932e/EIPS/eip-20.md) datatoken contract for each data service, then mint datatokens.
|
||||
* _Publish and access data services:_ downloadable files or compute-to-data. Use Ocean to deploy a new [ERC721](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md) and [ERC20](https://github.com/ethereum/EIPs/blob/7f4f0377730f5fc266824084188cc17cf246932e/EIPS/eip-20.md) datatoken contract for each data service, then mint datatokens.
|
||||
* _Transfer datatokens_ to another owner (or approve & transferFrom).
|
||||
* _Manage pools._ Deploy OCEAN-datatoken [Balancer](https://www.balancer.fi/) pools, buy & sell datatokens (swap), and add & remove liquidity.
|
||||
* _And more._ Use ERC20 support in [web3.js](https://web3js.readthedocs.io/), [web3.py](https://web3py.readthedocs.io/en/stable/examples.html#working-with-an-erc20-token-contract) and Solidity to connect datatokens with crypto wallets and other DeFi services.
|
||||
|
||||
- _Transfer datatokens_ to another owner (or approve & transferFrom).
|
||||
|
||||
- _Manage pools._ Deploy OCEAN-datatoken [Balancer](https://www.balancer.fi/) pools, buy & sell datatokens (swap), and add & remove liquidity.
|
||||
|
||||
- _And more._ Use ERC20 support in [web3.js](https://web3js.readthedocs.io/), [web3.py](https://web3py.readthedocs.io/en/stable/examples.html#working-with-an-erc20-token-contract) and Solidity to connect datatokens with crypto wallets and other DeFi services.
|
||||
|
||||
**Compute-to-Data**
|
||||
Ocean's "Compute-to-Data" feature gives compute access to privately-held data, which never leaves the data owner’s premises. Ocean-based marketplaces enable the monetization of private data while preserving privacy. [Here](/tutorials/compute-to-data-architecture/) are details.
|
||||
**Compute-to-Data** Ocean's "Compute-to-Data" feature gives compute access to privately-held data, which never leaves the data owner’s premises. Ocean-based marketplaces enable the monetization of private data while preserving privacy. [Here](tutorials/compute-to-data-architecture/) are details.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
# Table of contents
|
||||
|
||||
* [Orientation](README.md)
|
||||
* [API references](api-references/README.md)
|
||||
* [Aquarius REST API](api-references/aquarius-rest-api.md)
|
||||
* [Provider REST API](api-references/provider-rest-api.md)
|
||||
* [Core Concepts](core-concepts/README.md)
|
||||
* [Architecture Overview](core-concepts/architecture.md)
|
||||
* [Asset pricing](core-concepts/asset-pricing.md)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,2 @@
|
|||
# API references
|
||||
|
||||
|
|
@ -0,0 +1,323 @@
|
|||
# Aquarius REST API
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/aquarius/assets/ddo/did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479'
|
||||
```
|
||||
* 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
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/aquarius/assets/metadata/did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479'
|
||||
```
|
||||
* 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
|
||||
|
||||
```bash
|
||||
curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/aquarius/assets/names' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"didList" : ["did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479"]
|
||||
}'
|
||||
```
|
||||
* Responses
|
||||
* 200
|
||||
* content-type: json
|
||||
* description: successful operation.
|
||||
* response body:
|
||||
|
||||
```
|
||||
{"did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479": "Ocean Protocol Technical Whitepaper"}
|
||||
```
|
||||
* 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
|
||||
|
||||
```bash
|
||||
curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/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
|
||||
|
||||
```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 '<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
|
||||
|
||||
```bash
|
||||
curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/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
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/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
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/api/v1/aquarius/chains/status/137'
|
||||
```
|
||||
* Response
|
||||
* 200
|
||||
* Description: Successful request
|
||||
* Body
|
||||
|
||||
```
|
||||
{"last_block": 25198729}
|
||||
```
|
||||
|
||||
## Others
|
||||
|
||||
### **GET** `/`
|
||||
|
||||
* Description
|
||||
|
||||
Get version, plugin, and software information.
|
||||
* Example
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/'
|
||||
```
|
||||
* Response
|
||||
* 200
|
||||
* Description: Successful request
|
||||
* Body
|
||||
|
||||
```
|
||||
{
|
||||
"plugin": "elasticsearch",
|
||||
"software": "Aquarius",
|
||||
"version": "3.1.2"
|
||||
}
|
||||
```
|
||||
|
||||
### **GET** `/health`
|
||||
|
||||
* Description
|
||||
|
||||
Get health status
|
||||
* Example
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/health'
|
||||
```
|
||||
* Response
|
||||
* 200
|
||||
* Description: Successful request
|
||||
* Body
|
||||
|
||||
```
|
||||
Elasticsearch connected
|
||||
```
|
||||
|
||||
### **GET** /spec
|
||||
|
||||
* Description
|
||||
|
||||
Get swagger spec
|
||||
* Example
|
||||
|
||||
```bash
|
||||
curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/query/spec'
|
||||
```
|
||||
* Response
|
||||
* 200
|
||||
* Description: Successful request
|
||||
|
||||
### Postman documentation
|
||||
|
||||
Click [here](https://documenter.getpostman.com/view/2151723/UVkmQc7r) to explore the documentation and more examples in postman.
|
||||
|
|
@ -0,0 +1,545 @@
|
|||
# Provider REST API
|
||||
|
||||
## Ocean Provider Endpoints Specification
|
||||
|
||||
This document specifies the endpoints for Ocean Provider to be implemented by the core developers.
|
||||
|
||||
### nonce endpoint
|
||||
|
||||
#### GET /api/services/nonce
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
userAddress: String object containing a user's ethereum address
|
||||
```
|
||||
|
||||
Returns: Json object containing the nonce value.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/services/nonce?userAddress=0x990922334
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"nonce": 23
|
||||
}
|
||||
```
|
||||
|
||||
### Encrypt endpoint
|
||||
|
||||
#### GET /api/services/encrypt
|
||||
|
||||
Body: binary application/octet-stream
|
||||
|
||||
Returns: Bytes string containing the encrypted document.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/services/encrypt
|
||||
body: b'\xfd7zXZ\x00\x00\x04\xe6\xd6\xb4F\ ... \x00\x04YZ'
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
b'0x04b2bfab1f4e...7ed0573'
|
||||
```
|
||||
|
||||
### Decrypt endpoint
|
||||
|
||||
#### POST /api/services/decrypt
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
decrypterAddress: String object containing the address of the decrypter (required)
|
||||
chainId: the chain id of the network the document is on (required)
|
||||
transactionId: the transaction id of the encrypted document (optional)
|
||||
dataNftAddress: the address of the data nft (optional)
|
||||
encryptedDocument: the encrypted document (optional)
|
||||
flags: the flags of the encrypted document (optional)
|
||||
documentHash: the hash of the encrypted document (optional)
|
||||
nonce: the nonce of the encrypted document (required)
|
||||
signature: the signature of the encrypted document (required)
|
||||
```
|
||||
|
||||
Returns: Bytes string containing the decrypted document.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/services/decrypt
|
||||
payload: {
|
||||
'decrypterAddress':'0xA78deb2Fa79463945C247991075E2a0e98Ba7A09'
|
||||
'chainId':8996
|
||||
'dataNftAddress':'0xBD558814eE914800EbfeF4a1cbE196F5161823d9'
|
||||
'encryptedDocument':'0xfd377a585a0...f07afef7dc214'
|
||||
'flags': 1
|
||||
'documentHash':'0x0cb38a7bba49758a86f8556642aff655d00e41da28240d5ea0f596b74094d91f'
|
||||
'nonce':'1644315615.24195'
|
||||
'signature':'0xd6f27047853203824ab9e5acef87d0a501a64aee93f33a83b6f91cbe8fb4489824defceaccde91273f41290cb2a0c15572368e8bea0b456c7a653659cad7de311b'
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
b'{"@context": ["https://w3id.org/did/v1"], "id": "did:op:0c184915b07b44c888d468be85a9b28253e80070e5294b1aaed81c ...'
|
||||
```
|
||||
|
||||
### Initial service request endpoint
|
||||
|
||||
#### GET /api/services/initialize
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
documentId: String object containing document id (e.g. a DID)
|
||||
serviceId: String, ID of the service the datatoken is attached to
|
||||
consumerAddress: String object containing consumer's address
|
||||
environment: String representing a compute environment offered by the provider
|
||||
validUntil: Integer, date of validity of the service (optional)
|
||||
fileIndex: Integer, the index of the file from the files list in the dataset. If set, provider will validate the file access. (optional)
|
||||
```
|
||||
|
||||
Returns: Json document with a quote for amount of tokens to transfer to the provider account.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
GET /api/services/initialize
|
||||
payload:
|
||||
{
|
||||
"documentId":"0x1111",
|
||||
"serviceId": 0,
|
||||
"consumerAddress":"0x990922334",
|
||||
}
|
||||
payload (with optional parameters):
|
||||
{
|
||||
"documentId":"0x1111",
|
||||
"serviceId": 0,
|
||||
"consumerAddress":"0x990922334",
|
||||
"validUntil": 1578004800,
|
||||
"fileIndex": 1
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"datatoken": "0x21fa3ea32892091...",
|
||||
"nonce": 23,
|
||||
"providerFee": {
|
||||
"providerFeeAddress": "0xabc123...",
|
||||
"providerFeeToken": "0xabc123...",
|
||||
"providerFeeAmount": "200",
|
||||
"providerData": "0xabc123...",
|
||||
"v": 27,
|
||||
"r": "0xabc123...",
|
||||
"s": "0xabc123...",
|
||||
"validUntil": 123456,
|
||||
}
|
||||
"computeAddress": "0x8123jdf8sdsa..."
|
||||
}
|
||||
```
|
||||
|
||||
### Download endpoint
|
||||
|
||||
#### GET /api/services/download
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
documentId: String object containing document id (e.g. a DID)
|
||||
serviceId: String, representing the list of `file` objects that describe each file in the dataset
|
||||
transferTxId: Hex string -- the id of on-chain transaction for approval of datatokens transfer
|
||||
given to the provider's account
|
||||
fileIndex: integer, the index of the file from the files list in the dataset
|
||||
nonce: Nonce
|
||||
consumerAddress: String object containing consumer's address
|
||||
signature: String object containg user signature (signed message)
|
||||
```
|
||||
|
||||
Returns: File stream
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/services/download
|
||||
payload:
|
||||
{
|
||||
"documentId":"0x1111",
|
||||
"serviceId": 0,
|
||||
"fileIndex": 0,
|
||||
"datatoken": "",
|
||||
"consumerAddress":"0x990922334",
|
||||
"signature":"0x00110011",
|
||||
"transferTxId": "0xa09fc23421345532e34829"
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"": ""
|
||||
}
|
||||
```
|
||||
|
||||
### File info endpoint
|
||||
|
||||
#### POST /api/services/fileinfo
|
||||
|
||||
Retrieves Content-Type and Content-Length from the given URL or asset.
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
type: String, either "url" or "asset"
|
||||
did: String, DID of the dataset
|
||||
hash: String, hash of the file
|
||||
url: String, URL of the file
|
||||
serviceId: String, ID of the service the datatoken is attached to
|
||||
```
|
||||
|
||||
Returns: Json document file info object
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/services/fileinfo
|
||||
payload:
|
||||
{
|
||||
"url": "https://s3.amazonaws.com/testfiles.oceanprotocol.com/info.0.json",
|
||||
"type": "url",
|
||||
"method": "GET",
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"contentLength":"1161"
|
||||
"contentType":"application/json"
|
||||
"index":0
|
||||
"valid": true
|
||||
},...
|
||||
]
|
||||
```
|
||||
|
||||
### Compute endpoints
|
||||
|
||||
All compute endpoints respond with an Array of status objects, each object describing a compute job info.
|
||||
|
||||
Each status object will contain:
|
||||
|
||||
```
|
||||
owner:The owner of this compute job
|
||||
documentId: String object containing document id (e.g. a DID)
|
||||
jobId: String object containing workflowId
|
||||
dateCreated: Unix timestamp of job creation
|
||||
dateFinished: Unix timestamp when job finished (null if job not finished)
|
||||
status: Int, see below for list
|
||||
statusText: String, see below
|
||||
algorithmLogUrl: URL to get the algo log (for user)
|
||||
resultsUrls: Array of URLs for algo outputs
|
||||
resultsDid: If published, the DID
|
||||
```
|
||||
|
||||
Status description (`statusText`): (see Operator-Service for full status list)
|
||||
|
||||
| status | Description |
|
||||
| ------ | ----------------------------- |
|
||||
| 1 | Warming up |
|
||||
| 10 | Job started |
|
||||
| 20 | Configuring volumes |
|
||||
| 30 | Provisioning success |
|
||||
| 31 | Data provisioning failed |
|
||||
| 32 | Algorithm provisioning failed |
|
||||
| 40 | Running algorith |
|
||||
| 50 | Filtering results |
|
||||
| 60 | Publishing results |
|
||||
| 70 | Job completed |
|
||||
|
||||
### Create new job or restart an existing stopped job
|
||||
|
||||
#### POST /api/services/compute
|
||||
|
||||
Start a new job
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
signature: String object containg user signature (signed message) (required)
|
||||
consumerAddress: String object containing consumer's ethereum address (required)
|
||||
nonce: Integer, Nonce (required)
|
||||
environment: String representing a compute environment offered by the provider
|
||||
dataset: Json object containing dataset information
|
||||
dataset.documentId: String, object containing document id (e.g. a DID) (required)
|
||||
dataset.serviceId: String, ID of the service the datatoken is attached to (required)
|
||||
dataset.transferTxId: Hex string, the id of on-chain transaction for approval of datatokens transfer
|
||||
given to the provider's account (required)
|
||||
dataset.userdata: Json, user-defined parameters passed to the dataset service (optional)
|
||||
algorithm: Json object, containing algorithm information
|
||||
algorithm.documentId: Hex string, the did of the algorithm to be executed (optional)
|
||||
algorithm.meta: Json object, defines the algorithm attributes and url or raw code (optional)
|
||||
algorithm.serviceId: String, ID of the service to use to process the algorithm (optional)
|
||||
algorithm.transferTxId: Hex string, the id of on-chain transaction of the order to use the algorithm (optional)
|
||||
algorithm.userdata: Json, user-defined parameters passed to the algorithm running service (optional)
|
||||
algorithm.algocustomdata: Json object, algorithm custom parameters (optional)
|
||||
additionalDatasets: Json object containing a list of dataset objects (optional)
|
||||
|
||||
One of `algorithm.documentId` or `algorithm.meta` is required, `algorithm.meta` takes precedence
|
||||
```
|
||||
|
||||
Returns: Array of `status` objects as described above, in this case the array will have only one object
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
POST /api/compute
|
||||
payload:
|
||||
{
|
||||
"signature": "0x00110011",
|
||||
"consumerAddress": "0x123abc",
|
||||
"nonce": 1,
|
||||
"environment": "env",
|
||||
"dataset": {
|
||||
"documentId": "did:op:2222...",
|
||||
"serviceId": "compute",
|
||||
"transferTxId": "0x0232123..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"jobId": "0x1111:001",
|
||||
"status": 1,
|
||||
"statusText": "Job started",
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Status and Result
|
||||
|
||||
#### GET /api/services/compute
|
||||
|
||||
Get all jobs and corresponding stats
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
signature: String object containg user signature (signed message)
|
||||
documentId: String object containing document did (optional)
|
||||
jobId: String object containing workflowID (optional)
|
||||
consumerAddress: String object containing consumer's address (optional)
|
||||
|
||||
At least one parameter from documentId, jobId and owner is required (can be any of them)
|
||||
```
|
||||
|
||||
Returns
|
||||
|
||||
Array of `status` objects as described above
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
GET /api/services/compute?signature=0x00110011&documentId=did:op:1111&jobId=012023
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"owner": "0x1111",
|
||||
"documentId": "did:op:2222",
|
||||
"jobId": "3333",
|
||||
"dateCreated": "2020-10-01T01:00:00Z",
|
||||
"dateFinished": "2020-10-01T01:00:00Z",
|
||||
"status": 5,
|
||||
"statusText": "Job finished",
|
||||
"algorithmLogUrl": "http://example.net/logs/algo.log",
|
||||
"resultsUrls": [
|
||||
"http://example.net/logs/output/0",
|
||||
"http://example.net/logs/output/1"
|
||||
],
|
||||
"resultsDid": "did:op:87bdaabb33354d2eb014af5091c604fb4b0f67dc6cca4d18a96547bffdc27bcf"
|
||||
},
|
||||
{
|
||||
"owner": "0x1111",
|
||||
"documentId": "did:op:2222",
|
||||
"jobId": "3334",
|
||||
"dateCreated": "2020-10-01T01:00:00Z",
|
||||
"dateFinished": "2020-10-01T01:00:00Z",
|
||||
"status": 5,
|
||||
"statusText": "Job finished",
|
||||
"algorithmLogUrl": "http://example.net/logs2/algo.log",
|
||||
"resultsUrls": [
|
||||
"http://example.net/logs2/output/0",
|
||||
"http://example.net/logs2/output/1"
|
||||
],
|
||||
"resultsDid": ""
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Stop
|
||||
|
||||
#### PUT /api/services/compute
|
||||
|
||||
Stop a running compute job.
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
signature: String object containg user signature (signed message)
|
||||
documentId: String object containing document did (optional)
|
||||
jobId: String object containing workflowID (optional)
|
||||
consumerAddress: String object containing consumer's address (optional)
|
||||
|
||||
At least one parameter from documentId,jobId and owner is required (can be any of them)
|
||||
```
|
||||
|
||||
Returns
|
||||
|
||||
Array of `status` objects as described above
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
PUT /api/services/compute?signature=0x00110011&documentId=did:op:1111&jobId=012023
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
...,
|
||||
"status": 7,
|
||||
"statusText": "Job stopped",
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
#### DELETE /api/services/compute
|
||||
|
||||
Delete a compute job and all resources associated with the job. If job is running it will be stopped first.
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
signature: String object containg user signature (signed message)
|
||||
documentId: String object containing document did (optional)
|
||||
jobId: String object containing workflowId (optional)
|
||||
consumerAddress: String object containing consumer's address (optional)
|
||||
|
||||
At least one parameter from documentId, jobId is required (can be any of them)
|
||||
in addition to consumerAddress and signature
|
||||
```
|
||||
|
||||
Returns
|
||||
|
||||
Array of `status` objects as described above
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
DELETE /api/services/compute?signature=0x00110011&documentId=did:op:1111&jobId=012023
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
...,
|
||||
"status": 8,
|
||||
"statusText": "Job deleted successfully",
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### GET /api/services/computeResult
|
||||
|
||||
Allows download of asset data file.
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
jobId: String object containing workflowId (optional)
|
||||
index: Integer, index of the result to download (optional)
|
||||
consumerAddress: String object containing consumer's address (optional)
|
||||
nonce: Integer, Nonce (required)
|
||||
signature: String object containg user signature (signed message)
|
||||
```
|
||||
|
||||
Returns: Bytes string containing the compute result.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
GET /api/services/computeResult?index=0&consumerAddress=0xA78deb2Fa79463945C247991075E2a0e98Ba7A09&jobId=4d32947065bb46c8b87c1f7adfb7ed8b&nonce=1644317370
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
b'{"result": "0x0000000000000000000000000000000000000000000000000000000000000001"}'
|
||||
```
|
||||
|
||||
#### GET /api/services/computeEnvironments
|
||||
|
||||
Allows download of asset data file.
|
||||
|
||||
Parameters
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
Returns: List of compute environments.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
GET /api/services/computeEnvironments
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"cpuType":"AMD Ryzen 7 5800X 8-Core Processor"
|
||||
"currentJobs":0
|
||||
"desc":"This is a mocked enviroment"
|
||||
"diskGB":2
|
||||
"gpuType":"AMD RX570"
|
||||
"id":"ocean-compute"
|
||||
"maxJobs":10
|
||||
"nCPU":2
|
||||
"nGPU":0
|
||||
"priceMin":2.3
|
||||
"ramGB":1
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
Loading…
Reference in New Issue