From 507b2c98301445d82e89857ff29bc327d652aa90 Mon Sep 17 00:00:00 2001
From: mariacarmina <50501033+mariacarmina@users.noreply.github.com>
Date: Tue, 29 Nov 2022 03:46:25 -0800
Subject: [PATCH] Added context to the backend components API. (#1157)

* Updated provider-api.md.

* Updated DID to make examples work for aqua api.
---
 api-references/aquarius-rest-api.md |   8 +-
 api-references/provider-rest-api.md | 173 +++++++++++++++-------------
 2 files changed, 94 insertions(+), 87 deletions(-)

diff --git a/api-references/aquarius-rest-api.md b/api-references/aquarius-rest-api.md
index 954174fb..6696b832 100644
--- a/api-references/aquarius-rest-api.md
+++ b/api-references/aquarius-rest-api.md
@@ -15,7 +15,7 @@
 *   Example
 
     ```bash
-    curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/ddo/did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479'
+    curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/ddo/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6'
     ```
 * Responses
   * 200
@@ -45,7 +45,7 @@
 *   Example
 
     ```bash
-    curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/metadata/did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479'
+    curl --location --request GET 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/metadata/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6'
     ```
 * Responses
   * 200
@@ -78,7 +78,7 @@
     curl --location --request POST 'https://v4.aquarius.oceanprotocol.com/api/aquarius/assets/names' \
     --header 'Content-Type: application/json' \
     --data-raw '{
-        "didList" : ["did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479"]
+        "didList" : ["did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6"]
     }'
     ```
 * Responses
@@ -88,7 +88,7 @@
     *   response body:
 
         ```
-        {"did:op:CbD7aeecB5DFbABaB9126B5Cf1262dCFBA178479": "Ocean Protocol Technical Whitepaper"}
+        {"did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6": "Ocean CEX Aggregator: OHLC history for OCEAN/USDT "}
         ```
   * 400
     * content-type: json
diff --git a/api-references/provider-rest-api.md b/api-references/provider-rest-api.md
index 1e99e0ae..20af7b3a 100644
--- a/api-references/provider-rest-api.md
+++ b/api-references/provider-rest-api.md
@@ -14,7 +14,10 @@ Parameters
     userAddress: String object containing a user's ethereum address
 ```
 
-Returns: Json object containing the nonce value.
+Returns: Json object containing the last-used nonce value. 
+The nonce endpoint is just informative, use the current UTC timestamp as a nonce, 
+where required in other endpoints.
+
 
 Example:
 
@@ -93,6 +96,52 @@ Response:
 b'{"@context": ["https://w3id.org/did/v1"], "id": "did:op:0c184915b07b44c888d468be85a9b28253e80070e5294b1aaed81c ...'
 ```
 
+### File info endpoint
+
+#### POST /api/services/fileinfo
+
+Retrieves Content-Type and Content-Length from the given URL or asset.
+
+Parameters
+
+For published assets:
+```
+{
+    did: String, DID of the dataset
+    serviceId: String, ID of the service
+}
+```
+For file objects,see https://docs.oceanprotocol.com/core-concepts/did-ddo#files
+
+If checksum is requests, file size should be lower < MAX_CHECKSUM_LENGTH (see Provider ENVs)
+If file is larger, checksum WILL NOT be computed.
+
+Returns: Json document file info object
+
+Example:
+
+```
+POST /api/services/fileinfo
+payload:
+{
+    "did":"0x1111",
+    "serviceId": "0",
+}
+```
+
+Response:
+
+```json
+[
+    {
+        "contentLength":"1161",
+        "contentType":"application/json",
+        "index":0,
+        "valid": true
+    },...
+]
+```
+
 ### Initial service request endpoint
 
 #### GET /api/services/initialize
@@ -167,12 +216,12 @@ Parameters
     signature: String object containg user signature (signed message)
 ```
 
-Returns: File stream
+Returns: File stream. Retrieves the attached asset files.
 
 Example:
 
 ```
-POST /api/services/download
+GET /api/services/download
 payload:
 {
     "documentId":"0x1111",
@@ -192,48 +241,6 @@ Response:
 }
 ```
 
-### 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
 
@@ -397,6 +404,34 @@ Response:
 ]
 ```
 
+#### 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"}'
+```
+
 ### Stop
 
 #### PUT /api/services/compute
@@ -478,34 +513,6 @@ Response:
 ]
 ```
 
-#### 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.
@@ -528,16 +535,16 @@ 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
+        "cpuType":"AMD Ryzen 7 5800X 8-Core Processor",
+        "currentJobs":0,
+        "desc":"This is a mocked environment",
+        "diskGB":2,
+        "gpuType":"AMD RX570",
+        "id":"ocean-compute",
+        "maxJobs":10,
+        "nCPU":2,
+        "nGPU":0,
+        "priceMin":2.3,
         "ramGB":1
     },
     ...