Document unused fields in RPC Requests

Author: segeljakt

docs/RPC.md

@@ -140,6 +140,8 @@ Else it will contain the reply JSON data, e.g:
 * Credentials: A valid Colony Private Key
 * Returns: An [Executor object](../pkg/core/executor.go)
 
+*Note: The state and commissiontime fields are set by the server. The executor is always created in a PENDING state.*
+
 #### Payload 
 ```json
 {
@@ -148,13 +150,14 @@ Else it will contain the reply JSON data, e.g:
         "executorid": "38df5bbbcf0ccb438d2e4151638e3967bf28a5654af6a7e5acc590c0e49fae06",
         "executortype": "test_executor_type",
         "name": "test_executor_name",
-        "colonyid": "405acc69052cf19ce23ddd238b73c74bfd78c65cf6ef57613b870470a26d6f95",
-        "cpu": "AMD Ryzen 9 5950X (32) @ 3.400GHz",
-        "cores": 32,
-        "mem": 80326,
-        "gpu": "NVIDIA GeForce RTX 2080 Ti Rev. A",
-        "gpus": 1,
-        "state": 0
+        "colonyname": "my_colony_name",
+        "capabilities": {
+            "hardware": {
+                "cpu": "AMD Ryzen 9 5950X",
+                "mem": "80326MB",
+                "nodes": 1
+            }
+        }
     }
 }
 ```
@@ -773,12 +776,13 @@ The state attribute can have the following values:
 * Credentials: A valid Executor Private Key and the Executor ID needs to match the ExecutorID assigned to the process
 * Returns: An [Attribute object](../pkg/core/attribute.go)
 
+*Note: The attributeid and targetprocessgraphid fields are generated by the server and will be ignored if provided.*
+
 #### Payload 
 ```json
 {
     "msgtype": "addattributemsg",
     "attribute": {
-        "attributeid": "216e26cb089032d2f941454e7db5f3ae1591eeb43eb477c3f8ed545b96d4f690",
         "targetid": "c4775cab695da8a77b503bbe29df8ae39dafd1c7fed3275dac11b436c1724dbf",
         "attributetype": 1,
         "key": "result",
@@ -1148,21 +1152,20 @@ The state attribute can have the following values:
 * Credentials: A valid Executor Private Key
 * Returns: A [Cron object](../pkg/core/cron.go)
 
+*Note: The cronid, initiatorid, initiatorname, and all state fields (nextrun, lastrun, prevprocessgraphid) are managed by the server and will be ignored if provided.*
+
 #### Payload 
 ```json
 {
     "msgtype": "addcronmsg",
     "cron": {
-        "cronid": "a-valid-sha256-hash-id",
         "name": "my_cron_job",
         "colonyname": "my_colony_name",
         "cronexpression": "0 0 * * *",
-        "interval": 86400,
+        "interval": -1,
         "random": false,
-        "nextrun": "2022-01-03T00:00:00Z",
-        "lastrun": "0001-01-01T00:00:00Z",
-        "prevprocessgraphid": "",
-        "workflowspec": "{\"name\":\"my_workflow\",\"colonyname\":\"my_colony_name\",\"funcspecs\":[{\"timeout\":-1,\"maxretries\":3,\"conditions\":{\"colonyname\":\"my_colony_name\",\"executortype\":\"test_executor_type\",\"mem\":1000,\"cores\":10,\"gpus\":1},\"env\":{\"test_key\":\"test_value\"}}]}"
+        "waitforprevprocessgraph": true,
+        "workflowspec": "{\"name\":\"my_workflow\",\"colonyname\":\"my_colony_name\",\"funcspecs\":[{\"timeout\":-1,\"maxretries\":3,\"conditions\":{\"colonyname\":\"my_colony_name\",\"executortype\":\"test_executor_type\"}}]}"
     }
 }
 ```
@@ -1302,18 +1305,18 @@ The state attribute can have the following values:
 * Credentials: A valid Executor Private Key
 * Returns: A [Generator object](../pkg/core/generator.go)
 
+*Note: The generatorid, initiatorid, initiatorname, and all state fields (lastrun, counter) are managed by the server and will be ignored if provided.*
+
 #### Payload 
 ```json
 {
     "msgtype": "addgeneratormsg",
     "generator": {
-        "generatorid": "a-valid-sha256-hash-id",
         "name": "my_generator",
         "colonyname": "my_colony_name",
-        "workflowspec": "{\"name\":\"my_workflow\",\"colonyname\":\"my_colony_name\",\"funcspecs\":[{\"timeout\":-1,\"maxretries\":3,\"conditions\":{\"colonyname\":\"my_colony_name\",\"executortype\":\"test_executor_type\",\"mem\":1000,\"cores\":10,\"gpus\":1},\"env\":{\"test_key\":\"test_value\"}}]}",
+        "workflowspec": "{\"name\":\"my_workflow\",\"colonyname\":\"my_colony_name\",\"funcspecs\":[{\"timeout\":-1,\"maxretries\":3,\"conditions\":{\"colonyname\":\"my_colony_name\",\"executortype\":\"test_executor_type\"}}]}",
         "trigger": 5,
-        "counter": 0,
-        "lastrun": "0001-01-01T00:00:00Z"
+        "timeout": 60
     }
 }
 ```
@@ -1465,19 +1468,19 @@ The state attribute can have the following values:
 * Credentials: A valid Executor Private Key
 * Returns: A [File object](../pkg/core/file.go)
 
+*Note: The fileid and added timestamp are set by the server and will be ignored if provided.*
+
 #### Payload 
 ```json
 {
     "msgtype": "addfilemsg",
     "file": {
-        "fileid": "a-valid-sha256-hash-id",
         "colonyname": "my_colony_name",
         "label": "my_file_label",
         "name": "example.txt",
         "size": 1024,
         "checksum": "checksum-hash",
-        "checksumtype": "SHA256",
-        "added": "2022-01-02T12:00:00Z"
+        "checksumalg": "SHA256"
     }
 }
 ```
@@ -1502,14 +1505,19 @@ The state attribute can have the following values:
 * Returns: An array of [File objects](../pkg/core/file.go)
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "getfilemsg",
     "colonyname": "my_colony_name",
+    // Use one of the following methods to identify the file(s).
+    // Method 1: Get a specific file by its unique ID (highest priority).
     "fileid": "a-valid-sha256-hash-id",
+
+    // Method 2: Get files by label and name (used if fileid is empty).
     "label": "my_file_label",
     "name": "example.txt",
-    "latest": true
+    "latest": true // Set to true to get only the most recent version.
 }
 ```
 
@@ -1594,11 +1602,16 @@ The state attribute can have the following values:
 * Returns: An empty JSON object {}
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "removefilemsg",
     "colonyname": "my_colony_name",
+    // Use one of the following methods to identify the file(s) for deletion.
+    // Method 1: Delete a specific file by its unique ID (highest priority).
     "fileid": "a-valid-sha256-hash-id",
+
+    // Method 2: Delete all versions of a file by label and name (used if fileid is empty).
     "label": "my_file_label",
     "name": "example.txt"
 }
@@ -1636,10 +1649,13 @@ The state attribute can have the following values:
 * Returns: An array of [Log objects](../pkg/core/log.go)
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "getlogsmsg",
     "colonyname": "my_colony_name",
+    // Specify either executorname or processid.
+    // If executorname is provided, processid is ignored.
     "processid": "a-valid-sha256-hash-id",
     "executorname": "my_executor_name",
     "count": 100,
@@ -1832,11 +1848,16 @@ The state attribute can have the following values:
 * Returns: A [Snapshot object](../pkg/core/snapshot.go)
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "getsnapshotmsg",
     "colonyname": "my_colony_name",
+    // Use one of the following methods to identify the snapshot.
+    // Method 1: Get by unique snapshot ID (highest priority).
     "snapshotid": "a-valid-sha256-hash-id",
+
+    // Method 2: Get by unique name (used if snapshotid is empty).
     "name": "snapshot_2022_01_02"
 }
 ```
@@ -1884,11 +1905,16 @@ The state attribute can have the following values:
 * Returns: An empty JSON object {}
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "removesnapshotmsg",
     "colonyname": "my_colony_name",
+    // Use one of the following methods to identify the snapshot for deletion.
+    // Method 1: Delete by unique snapshot ID (highest priority).
     "snapshotid": "a-valid-sha256-hash-id",
+
+    // Method 2: Delete by unique name (used if snapshotid is empty).
     "name": "snapshot_2022_01_02"
 }
 ```
@@ -2000,23 +2026,16 @@ The state attribute can have the following values:
 * Credentials: A valid Executor Private Key
 * Returns: A [Function object](../pkg/core/function.go)
 
+*Note: The functionid and executortype fields are set by the server and will be ignored if provided.*
+
 #### Payload 
 ```json
 {
     "msgtype": "addfunctionmsg",
     "fun": {
-        "functionid": "a-valid-sha256-hash-id",
         "executorname": "my_executor_name",
-        "executortype": "test_executor_type",
         "colonyname": "my_colony_name",
-        "funcname": "calculate_sum",
-        "counter": 5,
-        "minwaittime": 2.0,
-        "maxwaittime": 3.0,
-        "minexectime": 9.5,
-        "maxexectime": 10.8,
-        "avgwaittime": 2.5,
-        "avgexectime": 10.1
+        "funcname": "calculate_sum"
     }
 }
 ```
@@ -2046,10 +2065,14 @@ The state attribute can have the following values:
 * Comments: If `executorname` is not provided, the functions of all executors in the specified colony will be returned.
 
 #### Payload 
+*Note: Comments (//) are for documentation and must be removed before sending the request.*
 ```json
 {
     "msgtype": "getfunctionsmsg",
     "colonyname": "my_colony_name",
+    // This field is optional.
+    // If provided, returns functions for a specific executor.
+    // If omitted, returns all functions in the colony.
     "executorname": "my_executor"
 }
 ```