The JDocs Services¶
The Vic-Cloud services stores information on a "JDocs" server. This unusual name appears to be short for "JSON Documents." This server allows Vector to store settings and usage statistics. This allows the settings and usage to be viewed on a mobile device on a remote network.
The interactions are basic: store, read, and delete a JSON blob by an identifier. The description below gives the JSON keys, value format. It is implemented as gRPC/protobuf interaction over HTTP.
The commands include:
- An 'echo' command to check connectivity with the server.
- Reading and writing a document
- Deleting a document
- Viewing account documents
Common Elements¶
The enumerations and structures in this section are common to many commands.
Enumerations¶
Status¶
Structures¶
JDoc¶
The JDoc structure has the following fields:
Table: JSON structure
| Field | Type | Description |
|---|---|---|
| client_meta | string | Probably an empty string |
| doc_version | uint64 | A number used to uniquely identify changes to the setting structure, and be able to tell which ones is the more recent settings. Most often this is the number of times that the settings have been changed. |
| fmt_version | uint64 | The version number of the jdoc structure schema; this is always 1. |
| json_doc | string | The jdoc structure serialized as a string. |
Commands and Responses¶
Delete Document¶
This is used to remove the document from the server.
Request¶
The DeleteDocReq request message has the following fields:
Table: JSON Parameters for delete document request
| Field | Type | Description |
|---|---|---|
| account | string | The account to delete the document from. |
| doc_name | string | The name of the document to delete. |
| thing | string | The thing id is a 'vic:' followed by the serial number |
Response¶
The DeleteDocResp response message has the following fields:
Table: JSON Parameters for the delete document response
| Field | Type | Description |
|---|---|---|
| latest_version | uint64 | The current version of the document in the repository. |
| status | string |
Echo Test¶
Request¶
The EchoReq request message has the following fields:
Table: JSON Parameters for the echo request
| Field | Type | Description |
|---|---|---|
| data |
Response¶
The EchoResp response message has the following fields:
Table: JSON Parameters for the echo response
| Field | Type | Description |
|---|---|---|
| data | comment: I'm not sure this field is sent back |
Read Documents¶
Request¶
The ReadDocsReq request message has the following fields:
Table: JSON Parameters for the read documents request
| Field | Type | Description |
|---|---|---|
| account | string | The account to read from. |
| items | ReadDocsReq_Item [] | Array of the items requested. |
| thing | string | The thing id is a 'vic:' followed by the serial number. |
The ReadDocsReq_Item structure has the following fields:
Table: JSON Parameters for the read documents item
| Field | Type | Description |
|---|---|---|
| doc_name | string | The name of the document to retrieve. |
| my_doc_version | UInt64 | The version to retrieve(?) |
Response¶
The ReadDocsResp response message has the following fields:
Table: JSON Parameters for the read documents response
| Field | Type | Description |
|---|---|---|
| items | _ReadDocsResp_item[] | An array of the documents. |
The ReadDocsResp_Item structure has the following fields:
Table: JSON Parameters for the read document item response
| Field | Type | Description |
|---|---|---|
| doc | JDoc | The document structure. |
| status | Status |
View Account Document¶
This command is used to retrieve a JSON blob on the server. The request allows personally identifying information to be included or omitted.
Request¶
The ViewDocReq request message has the following fields:
Table: JSON Parameters for view account document request
| Field | Type | Description |
|---|---|---|
| account | string | The account to read from. |
| json_doc | JDoc | The document structure. {TODO: why is this here? this makes it seem like it doesn’t } Optional |
| doc_name | string | The name of the document to view. Optional |
| thing | string | The thing id is a ‘vic:’ followed by the serial number. Optional |
Response¶
The ViewDocsResp response message has the following fields:
Table: JSON Parameters for view account document response
| Field | Type | Description |
|---|---|---|
| docs | TBD[] | The documents (?) |
Write Document¶
This command is used to store a JSON blob on the server.
Request¶
The WriteDocReq request message has the following fields:
Table: JSON Parameters for write document request
| Field | Type | Description |
|---|---|---|
| account | string | The account to write to. |
| doc | JDoc | The document structure. |
| doc_name | string | The name of the document to write. |
| thing | string | The thing id is a 'vic:' followed by the serial number. |
Response¶
The WriteDocResp response message has the following fields:
Table: JSON Parameters for write document response
| Field | Type | Description |
|---|---|---|
| latest_doc_version | UInt64 | The current version of the document in the repository. |
| status | Status |