Merge pull request #46 from polybase/eng-331-api-ref-examples-doesnt-work-for-list

Add clarification to auth header and body args

Author: calummoore

api-reference/call-function.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Call a function"
-api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records/<record_id>/call/<function_name>"
+api: "POST https://testnet.polybase.xyz/v0/collections/{collection_path}/records/{record_id}/call/{function_name}"
 ---
 
 <RequestExample>
@@ -9,6 +9,9 @@ api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records
 curl --request POST \
      --url https://testnet.polybase.xyz/v0/collections/polybase%2Fcore%2Fusers/records/id123/call/functionName\
      --header 'Accept: application/json'
+     -d '{ "args": ["Polybase"] }' 
+     # optional (if supplied ctx.publicKey will be populated)
+     --header 'X-Polybase-Signature: v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c'
 ```
 
 </RequestExample>
@@ -32,4 +35,32 @@ curl --request POST \
 
 <ParamField body="args" type="array" required>
   An array of arguments that should be passed to the the function being called on the collection, as defined in the collection schema.
+
+  For example, if the collection schema is as follows:
+
+  ```js
+    collection Users {
+      id: string;
+      name: string;
+
+      constructor (name: string) {
+        this.id = PublicKey;
+        this.name = name;
+      }
+
+      setName(name: string) {
+        this.name = name;
+      }
+    }
+  ```
+
+  The args would be:
+  ```json
+  {
+    args: [
+      // This is the 1st parameter name: string
+      "Polybase"
+    ]
+  }
+  ```
 </ParamField>

api-reference/create-record.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Create a record"
-api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records"
+api: "POST https://testnet.polybase.xyz/v0/collections/{collection_path}/records"
 ---
 
 <RequestExample>
@@ -9,6 +9,9 @@ api: "POST https://testnet.polybase.xyz/v0/collections/<collection_path>/records
 curl --request POST \
      --url https://testnet.polybase.xyz/v0/collections/polybase%2Fcore%2Fusers/records\
      --header 'Accept: application/json'
+     -d '{ "args": ["Polybase"] }' 
+     # optional (if supplied ctx.publicKey will be populated)
+     --header 'X-Polybase-Signature: v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c'
 ```
 
 </RequestExample>
@@ -22,5 +25,31 @@ curl --request POST \
 ## Body Params
 
 <ParamField body="args" type="array" required>
-  An array of arguments that should be passed to the the constructor of the collection, as defined in the collection schema.
+  An array of arguments that should be passed to the the `constructor` of the collection, as defined in the collection schema. For example, if the collection schema is as follows:
+
+  ```js
+    collection Users {
+      id: string;
+      name: string;
+      age: number;
+
+      constructor (name: string, age: number) {
+        this.id = PublicKey;
+        this.name = name;
+        this.age = age;
+      }
+    }
+  ```
+
+  The args would be:
+  ```json
+  {
+    args: [
+      // This is the 1st parameter name: string
+      "Polybase",
+      // This is the 2nd parameter age: number
+      1
+    ]
+  }
+  ```
 </ParamField>

api-reference/get-record.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Get record"
-api: "GET https://testnet.polybase.xyz/v0/collections/<collection_path>/records/<record_id>"
+api: "GET https://testnet.polybase.xyz/v0/collections/{collection_path}/records/<record_id>"
 ---
 
 <RequestExample>

api-reference/list-records.mdx

@@ -1,6 +1,6 @@
 ---
 title: "List records"
-api: "GET https://testnet.polybase.xyz/v0/collections/<collection_path>/records"
+api: "GET https://testnet.polybase.xyz/v0/collections/{collection_path}/records"
 ---
 
 <RequestExample>

api-reference/overview.mdx

@@ -15,9 +15,10 @@ The Polybase Gatweay API uses public/private key pair for authentication. That m
 Authentication is composed of:
 
  - `v` the version being used, should be `v=0` 
- - `t` current unix timestamp in seconds
+ - `t` current unix timestamp in milliseconds
  - `h` type of hash signing being used `eth-personal-sign` is currently the only allowed option
- - `sig` the signature of the data 
+ - `sig` the signature of the data (see below)
+ - `pk` **optional** 65 byte public key (secp256k1 algorithm)
 
 
 An example of a valid authroization:
@@ -26,4 +27,24 @@ An example of a valid authroization:
 v=0,t=1671884992,h=eth-personal-sign,sig=0x288db6271d92253ae19983a8e5110f1bc1bef1911210127ccbf657d85428ba9917aa9457f0f8e7f300a36b106525d3a3471e63ae265af4898742040a377e1da11c
 ```
 
-The token is passed in the `X-Polybase-Signature` header of the request.
+The token is passed in the `X-Polybase-Signature` header of the request.
+
+
+### Signature (`sig`)
+
+To generate `sig` you must sign a string in the format `<timestamp>.<body_json>`. Where `timestamp` is the `t` you provided above, and `body_json` is the body of the request (as a JSON string).
+
+You can use the [@polybase/util](https://www.npmjs.com/package/@polybase/util) package to generate the signature from any 32 bytes private key, and the sign function to create the signature.
+
+```typescript
+import { secp256k1 } from '@polybase/util'
+
+// You can use any 32 byte private key from any library, 
+// here is an example from @polybase/util
+let private_key = secp256k1.generatePrivateKey();
+
+function createSig (timestamp, body) {
+  const str_to_sign = `${timestamp}.${JSON.stringify(body)}`;
+  return secp256k1.sign(privateKey, str_to_sign);
+}
+```