Transaction Envelope¶
Most RESTful Endpoints respond with this JSON object, where response is populated
by an endpoint-specific schema. The Transaction Envelope schema enables providing
error information, request context, and other useful fields about the request and response payload for the specific API call.
The Acroname Devices, Acroname Devices State endpoint , Devices, and BrainStem endpoints use this schema as an envelope.
The Version endpoint does not use this envelope.
JSON Schema for Transaction Envelope¶
The following table lists a JSON Schema .
Download the raw JSON Schema file: transaction_envelope.json
Object Fields of BrainD V1 Transaction Envelope¶
Name |
Type |
Mandatory |
Description |
|---|---|---|---|
|
Yes |
||
|
v1-error or boolean or object or array or number or string |
Yes |
|
|
Array<null> |
No |
|
|
Yes |
When the call completed, in ISO8601 time. |
Object Fields of request¶
Name |
Type |
Mandatory |
Description |
|---|---|---|---|
|
string |
Yes |
Path-section of the URL |
|
No |
Parameters decoded from the HTTP body. |
Object Fields of request.params¶
Name |
Type |
Mandatory |
Description |
|---|
v1-aErr¶
Name |
Value |
|---|---|
Type |
string |
description |
Enumeration of all possible error results |
Enumerations |
|
v1-error¶
Name |
Value |
|---|---|
Type |
|
description |
Error containing an acroname error |
Name |
Type |
Mandatory |
Description |
|---|---|---|---|
|
Yes |
Acroname error code |
|
|
string |
No |
A human-readable message to describe the context of the error. |
v1-timestamp¶
Name |
Value |
|---|---|
Type |
string |
description |
String containing a ISO8601 timestamp (YYYY-MM-DDTHH:MM:SS.mmmZ |
Regular Expression |
|
Examples¶
These are examples of payloads for endpoints that use a transaction envelope. These examples closely follow the examples on every endpoint’s reference page, but include the envelope for verbosity.
Acroname Devices¶
The success-case of response is detailed in Acroname Devices endpoint
page.
curl http://127.0.0.1:9005/api/v1/acronameDevices
A reasonable output in the expected case:
1{
2 "timestamp": "2023-09-20T17:11:54.092Z",
3 "request": {
4 "endpointName": "/api/v1/acronameDevices",
5 "parameters": {}
6 },
7 "response": {
8 "acronameDevices": [
9 {
10 "type": "USB",
11 "serialNumber": "3C43352C",
12 "module": 6,
13 "model": "USBHub3c",
14 "entitlements": [
15 {
16 "tag": "CONTROL",
17 "version": 0
18 }
19 ]
20 },
21 {
22 "type": "USB",
23 "serialNumber": "F7D9AFB6",
24 "module": 6,
25 "model": "USBHub3p",
26 "entitlements": [
27 {
28 "tag": "CONTROL",
29 "version": 0
30 }
31 ]
32 }
33 ]
34 }
35}
The Acroname Device endpoint does not emit errors. But if it did, it might look something like:
1{
2 "timestamp": "2023-10-05T18:34:30.200Z",
3 "request": {
4 "endpointName": "/api/v1/acronameDevices",
5 "parameters": {}
6 },
7 "response": {
8 "errorCode": "aErrUnknown",
9 "errorMessage": "Unhandled exception while gathering device names."
10 }
11}
Acroname Devices State¶
The success-case of response is detailed in Acroname Devices State endpoint
page.
curl http://127.0.0.1:9005/api/v1/acronameDevicesState
A reasonable output in the expected case:
1{
2 "timestamp": "2023-09-20T17:24:24.428Z",
3 "request": {
4 "endpointName": "/api/v1/acronameDevicesState",
5 "parameters": {}
6 },
7 "response": {
8 "timestamp": "2023-09-20T17:24:24.108Z",
9 "sequence": 2563,
10 "brainstemVersion": {
11 "major": 2,
12 "minor": 10,
13 "patch": 0
14 },
15 "acronameDevices": [
16 {
17 "serialNumber": "0x3C43352C",
18 "firmwareVersion": {
19 "major": 2,
20 "minor": 10,
21 "patch": 0
22 },
23 "model": "USBHub3c",
24 "upstreamPort": 0,
25 "upstreamPortSelectionIsAutomatic": true,
26 "ports": [
27 {
28 "index": 0,
29 "physicalName": "Port 0",
30 "speed": "5 Gbps",
31 "roles": [
32 "Upstream",
33 "Downstream"
34 ],
35 "currentDataRole": "Upstream",
36 "enabled": true,
37 "voltage": {
38 "value": 5.207519,
39 "units": "volts",
40 "rawValue": 5207519
41 },
42 "current": {
43 "value": 0.00061,
44 "units": "amperes",
45 "rawValue": 610
46 }
47 },
48 {
49 "index": 1,
50 "physicalName": "Port 1",
51 "speed": "Unknown",
52 "roles": [
53 "Upstream",
54 "Downstream"
55 ],
56 "currentDataRole": "Downstream",
57 "enabled": true,
58 "voltage": {
59 "value": 0.0,
60 "units": "volts",
61 "rawValue": 0
62 },
63 "current": {
64 "value": 0.000305,
65 "units": "amperes",
66 "rawValue": 305
67 }
68 },
69 <additional ports ...>
70 ]
71 }
72 ]
73 }
74}
The Acroname Devices State endpoint emits an error in the case where licenses were not found.
1{
2 "timestamp": "2023-10-05T18:57:49.317Z",
3 "request": {
4 "endpointName": "/api/v1/acronameDevicesState",
5 "parameters": {}
6 },
7 "response": {
8 "errorCode": "aErrPermission",
9 "errorMessage": "The call is not allowed, check permissions and licenses associated with this call"
10 }
11}
Devices¶
The success-case of response is detailed in the Devices endpoint
page.
curl http://127.0.0.1:9005/api/v1/devices
A reasonable output in the expected case:
1{
2 "timestamp": "2023-09-20T17:36:15.359Z",
3 "request": {
4 "endpointName": "/api/v1/devices",
5 "parameters": {}
6 },
7 "response": {
8 "usb": [
9 {
10 "vendorId": "0x067B",
11 "productId": "0x2303",
12 "speedActual": "12 Mbps",
13 "maxSpeed": "12 Mbps",
14 "productName": "USB-Serial Controller",
15 "serialNumber": "",
16 "manufacturer": "Prolific Technology Inc.",
17 "deviceClass": 0,
18 "interfaces": [
19 {
20 "interfaceIndex": 0,
21 "entryIndex": 0,
22 "kClass": 255,
23 "kSubclass": 0,
24 "kProtocol": 0
25 }
26 ],
27 "portPath": [
28 4,
29 3,
30 1
31 ],
32 "acronameDevice": {
33 "serialNumber": "0xF7D9AFB6",
34 "port": 0,
35 "distance": 0
36 },
37 "bulkCapability": {
38 "isDoing": true,
39 "isCapable": true
40 },
41 "isochronousCapability": {
42 "isDoing": false,
43 "isCapable": false
44 },
45 "interruptCapability": {
46 "isDoing": true,
47 "isCapable": true
48 }
49 },
50 {
51 "vendorId": "0x2188",
52 "productId": "0x0747",
53 "speedActual": "5 Gbps",
54 "maxSpeed": "5 Gbps",
55 "productName": "Card Reader ",
56 "serialNumber": "000000000010",
57 "manufacturer": "CalDigit",
58 "deviceClass": 0,
59 "interfaces": [
60 {
61 "interfaceIndex": 0,
62 "entryIndex": 0,
63 "kClass": 8,
64 "kSubclass": 6,
65 "kProtocol": 80
66 }
67 ],
68 "portPath": [
69 4,
70 8
71 ],
72 "bulkCapability": {
73 "isDoing": true,
74 "isCapable": true
75 },
76 "isochronousCapability": {
77 "isDoing": false,
78 "isCapable": false
79 },
80 "interruptCapability": {
81 "isDoing": false,
82 "isCapable": false
83 }
84 }
85 ]
86 }
87}
The Devices endpoint emits an error in the case where licenses were not found.
1{
2 "timestamp": "2023-10-05T19:11:51.113Z",
3 "request": {
4 "endpointName": "/api/v1/devices",
5 "parameters": {}
6 },
7 "response": {
8 "errorCode": "aErrPermission",
9 "errorMessage": "The call is not allowed, check permissions and licenses associated with this call"
10 }
11}
BrainStem¶
The success-case of response is detailed in BrainStem Endnpoint page.
curl http://127.0.0.1:9005/api/v1/brainstem/3C43352C/system/0/inputvoltage
A reasonable output in the expected case:
1{
2 "timestamp": "2023-09-20T17:53:32.480Z",
3 "request": {
4 "endpointName": "/api/v1/brainstem/3C43352C/system/0/inputvoltage",
5 "parameters": {}
6 },
7 "response": {
8 "value": 22974139,
9 "rawValue": 22974139
10 }
11}
The BrainStem endpoint will emit errors specific to malformed requests, or hardware exceptions.
Example: Invalid value field supplied
1{
2 "timestamp": "2023-10-05T20:11:55.218Z",
3 "request": {
4 "endpointName": "/api/v1/brainstem/F2C3B5AC/port/5/Enabled/",
5 "parameters": {
6 "value": "🦁"
7 }
8 },
9 "response": {
10 "errorCode": "aErrParse",
11 "errorMessage": "Value can not be converted to an integer value."
12 }
13}
Example: 8-port hardare does not support index 9
1{
2 "timestamp": "2023-10-05T20:13:16.954Z",
3 "request": {
4 "endpointName": "/api/v1/brainstem/F2C3B5AC/port/9/Enabled/",
5 "parameters": {
6 "value": "1"
7 }
8 },
9 "response": {
10 "errorCode": "aErrUnimplemented",
11 "errorMessage": "Functionality unimplemented"
12 }
13}