Data exchange between devices is carried out according to the HTTP/2 protocol using the POST method. The contents of requests and responses are JSON objects. Both methods of passing parameters from the client to the server are available - as a URL string after the "?" (where it is possible or necessary) or/and in the content of the request as a string describing the JSON object. The server always responds with a JSON object in the content of the response (excluding the getRecordData.json request).
The following requests are allowed
Streaming
Example of protocol application and possible message format for a client-server application
getConfig.json
Receiving a set of configurations from server. Description of the server configuration you can find here.
Request
The JSON object
Possible (alternative) query string https://localhost/getConfig.json?shash=string
Parameters
- shash - session id (required)
Response
JSON_OK response
{"config":[
{"kind":integer,
"descr":":string:",
"miv":double,
"mav":double,
"dv":double,
"fv":double},
...],
"result":"OK"}
- config - the array of configurations received
- kind - the integer id of a specific configuration
- descr - description for a specific configuration
- miv - minimum allowed value for a specific configuration
- mav - maximum allowed value for a specific configuration
- dv - default value for a specific configuration
- fv - current value for a specific configuration that applied for account
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getConfig.json
{"config":[{"kind":1,"descr":"old records timeout (days)","miv":4.0E-003,"mav":1.68E+002,"dv":3.0E+001,"fv":3.0E+001},{"kind":2,"descr":"dead sessions timeout (minutes)","miv":3.0E+000,"mav":3.0E+001,"dv":1.0E+001,"fv":1.0E+001},{"kind":3,"descr":"max requests for session","miv":2.0E+002,"mav":1.0E+004,"dv":1.5E+003,"fv":1.5E+003},{"kind":4,"descr":"max reqs per min for session","miv":2.0E+001,"mav":2.0E+002,"dv":5.0E+001,"fv":5.0E+001}],"result":"OK"}
setConfig.json
Send a set of configurations to server. Description of the server configuration you can find here.
Request
The JSON object
{"shash":":string:","config":[{"kind":integer,"fv":double},...]}
Possible (alternative) query string https://localhost/setConfig.json?shash=string&config=%5Bobject_array%5D
Parameters
- shash - session id (required)
- config - array of sent configurations
- kind - integer id of a specific configuration
- fv - current value for a specific configuration that applied for account
Response
JSON_OK response
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","config":[{"kind":1,"fv":1.0},{"kind":4,"fv":100}]}' -X POST https://localhost:8080/setConfig.json
{"result":"OK"}
A set of current REST Web Camera Server configurations
| kind | description | minimum | maximum | default |
| 1 | old records timeout (days) | 0.004 | 168 | 30 |
| 2 | dead sessions timeout (minutes) | 3 | 30 | 10 |
| 3 | max requests for session | 200 | 10000 | 1500 |
| 4 | max requests per minute for session | 20 | 200 | 50 |
Data stream format
A valid data stream is a sequence of frames of the following format:
+--------------+
| Data frame 1 |
+--------------+
| Data frame 2 |
+--------------+
.......
+--------------+
| Data frame N |
+--------------+
Each data frame has the format shown below (the number of bits is indicated in parentheses).
+-------------------+
| Header seq (16) | = 0xaaaa
+-------------------+
| Payload size (32) |
+-------------------+
| Payload (0..*) |
+-------------------+
output.raw
Receiving data stream from selected device to client.
Request
JSON object in request content is not allowed. Query string https://localhost/output.raw?shash=string&device=string
Parameters
Response
JSON_OK response
Server open the data stream from selected device. The description of data stream format you can find here
Example
> curl --http2 -k -X POST https://localhost:8080/output.raw?shash=ra5PNJRgzrqpwbfw8JvHIkWuxJE%3D&device=camera_device
input.raw
Open data stream from client device to server.
Request
JSON object in request content is not allowed. Query string https://localhost/input.raw?shash=string&subproto=string&delta=integer The content of the request must contain formatted frames data.
Parameters
- shash - session id (required)
- subproto - the sub-protocol description (optional)
- delta - the maximum time interval between two consecutive frames in ms (optional)
Sub-protocol
There are no requirements for naming subprotocols. The set and description of subprotocols is determined within the account, since the encoding and decoding of frames is carried out on the client side. The specification describes only recommendations for the formation of similar names of subprotocols. The general format of the name of the subprotocol is as follows:
(COMPRESSION){1}_(FORMAT){1}(_[A-Z0-9]+)*
Examples:
DEFLATE_TEXT
RAW_JPEG
DEFLATE_JSON
LZMA_FILE_HEADER128B
Response
There is no formatted response. If an error occurs, the stream is closed by the host.
Example
curl --http2 -k --data-binary '@data.raw' -X POST https://localhost:8080/input.raw?shash=ra5PNJRgzrqpwbfw8JvHIkWuxJE%3D&subproto=RAW_JPEG
authorize.json
Authorizes the device on the server under the specified account.
Request
The JSON object
{"name":":string:", "pass":":string:", "device":":string:", "meta":":string:"}
Possible (alternative) query string https://localhost/authorize.json?name=string&pass=string&device=string&meta=string
Parameters
- name - the name of user's account (required)
- pass - the password for user's account (required)
- device - device name - a unique value within one account to identify the target and source of the message - usually the device's mac address (required)
- meta - metadata for this device (optional)
Response
JSON_OK response
{"shash":":string:", "result":"OK"}
- shash - new session id returned
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"name":"user","pass":"111","device":"user_pc","meta":"some info"}' -X POST https://localhost:8080/authorize.json
{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","result":"OK"}
addRecord.json
Send blob data and create new media record.
Request
JSON object in request content is not allowed. The content of the request must contain raw blob data.
Query string https://localhost/addRecord.json?shash=string&meta=string
Parameters
- shash - session id (required)
- meta - text data assigned to the media record by the client. For example, the format of the media record can be specified here. By default, the media record format is JPEG.
Response
JSON_OK response
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k --data-binary '@inp.png' -X POST https://localhost:8080/addRecordData.json?shash=ra5PNJRgzrqpwbfw8JvHIkWuxJE%3D&meta=PNG
{"result":"OK"}
addMsgs.json
Send messages to the server.
Request
The JSON object
variant 1
{"shash":":string:", "msg":":string:", "target":":string:", "params":{...}}
variant 2
{"shash":":string:", "msgs":[{"msg":":string:", "target":":string:", "params":{...}},...]}
Possible (alternative) query string https://localhost/addMsgs.json?shash=string&msg=string&device=string&target=string¶ms=string
Parameters
- shash - session id (required)
- msg - the name of the message inside the internal logic of your client-server application (required)
- target - message recipient device name (optional). If this parameter is empty, the message is broadcast and will be sent to all devices in the account.
- params - message parameters inside the internal logic of your client-server application (optional)
- msgs - the array of messages to send (optional)
Response
JSON_OK response
JSON_BAD response
JSON_BAD response format and description of error codes
Sync message
After receiving messages from the server, the client application must send a synchronization message, otherwise the messages will be resent by the server. The format of sync message is
{"shash":":string:", "msg":"sync"}
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","msg":"obey","params":{"please":1}}' -X POST https://localhost:8080/addMsgs.json
{"result":"OK"}
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","msgs":[{"msg":"status","target":"device1"},{"msg":"shutdown","target":"device2"}]' -X POST https://localhost:8080/addMsgs.json
{"result":"OK"}
getRecordMeta.json
Receiving metadata for a media record from the server.
Request
The JSON object
{"shash":":string:", "rid":integer}
Possible (alternative) query string https://localhost/getRecordMeta.json?shash=string&rid=integer
Parameters
- shash - session id (required)
- rid - the id of a media record (required). Value can be obtained with getRecordCount.json request
Response
JSON_OK response
{"device":":string:","meta":":string:","stamp":":string:","result":"OK"}
- device - media record emitter device name.
- meta - text data assigned to the media record by the client. For example, the format of the media record can be specified here. By default, the media record format is JPEG.
- stamp - the timestamp of a media record. The timestamp is in a format determined by the server and may not match the client's local settings.
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","rid":34}' -X POST https://localhost:8080/getRecordMeta.json
{"device":"34945423FA90","record":"","stamp":"2022-02-07 12:29:36","result":"OK"}
getRecordData.json
Receiving blob data for a media record from the server.
Request
The JSON object
{"shash":":string:", "rid":integer}
Possible (alternative) query string https://localhost/getRecordData.json?shash=string&rid=integer
Parameters
- shash - session id (required)
- rid - the id of a media record (required). Value can be obtained with getRecordCount.json request
Response
JSON_OK response
Server returns a raw blob data for selected media record.
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","rid":34}' -X POST https://localhost:8080/getRecordData.json -o out.jpg
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 41480 100 41431 100 49 299k 363 --:--:-- --:--:-- --:--:-- 302k
getRecordCount.json
Receiving a list of media records from the server. The server sends only a list of records, to get the data of the record, the client must request each record separately by getRecordData.json request.
Request
The JSON object
{"shash":":string:", "stamp":":string:"}
Possible (alternative) query string https://localhost/getRecordCount.json?shash=string&stamp=string
Parameters
- shash - session id (required)
- stamp - the timestamp of the last received media record. The server will send all media records that arrived later (not including) than the given timestamp (optional)
Response
JSON_OK response
{"records":[{"rid":integer,"device":":string:","stamp":":string:"},...],"result":"OK"}
- records - the array of media records received
- rid - the integer id of a media record
- device - record emitter device name.
- stamp - the timestamp of a media record. The timestamp is in a format determined by the server and may not match the client's local settings.
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getRecordCount.json
{"records":[{"rid":34,"device":"d1","stamp":"2022-02-07 12:29:36"}],"result":"OK"}
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","stamp":"2022-02-07 12:29:36"}' -X POST https://localhost:8080/getRecordCount.json
{"records":[],"result":"OK"}
getMsgsAndSync.json
Receiving messages from the server, then send sync message. The request and response formats are exactly the same as the getMsgs.json request/response, except that the server automatically adds a sync message for the requesting device.
getMsgs.json
Receiving messages from the server.
Request
The JSON object
{"shash":":string:", "stamp":":string:"}
Possible (alternative) query string https://localhost/getMsgs.json?shash=string&stamp=string
Parameters
- shash - session id (required)
- stamp - the timestamp of the last received message. The server will send all messages that arrived later (not include) than the given timestamp, otherwise all messages will be resent from the last sync message (optional)
Response
JSON_OK response
{"msgs":[{"msg":":string:","device":":string:","stamp":":string:","params":{...}},...],"result":"OK"}
- msgs - the array of messages received
- msg - the name of the message inside the internal logic of your client-server application
- device - message emitter device name.
- params - message parameters inside the internal logic of your client-server application
- stamp - the timestamp of the message. The timestamp is in a format determined by the server and may not match the client's local settings.
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getMsgs.json
{"msgs":[{"msg":"1","device":"dev1","params":{},"stamp":"2022-02-07 12:28:35"},{"msg":"2","device":"dev2","params":{},"stamp":"2022-02-07 14:00:00"}],"result":"OK"}
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","stamp":"2022-02-07 12:28:35"}' -X POST https://localhost:8080/getMsgs.json
{"msgs":[{"msg":"2","device":"dev2","params":{},"stamp":"2022-02-07 14:00:00"}],"result":"OK"}
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","msg":"sync"}' -X POST https://localhost:8080/addMsgs.json
{"result":"OK"}
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getMsgs.json
{"msgs":[],"result":"OK"}
getDevicesOnline.json
Obtaining a list of active (online) devices authorized under the same account
Request
The JSON object
Possible (alternative) query string https://localhost/getDevicesOnline.json?shash=string
Parameters
- shash - session id (required)
Response
JSON_OK response
{"result":"OK","devices":[{"device":":string:","meta":":string:"},...]}
- devices - array of online devices received
- device - the device name
- meta - the meta data for the device
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getDevicesOnline.json
{"result":"OK","devices":[{"device":"user_pc","meta":"some info"},{"device":"d1c","meta":"{\"param\":1}"},{"device":"d2","meta":"cam v0.3"}]}
getStreams.json
Obtaining a list of streaming devices authorized under the same account
Request
The JSON object
Possible (alternative) query string https://localhost/getStreams.json?shash=string
Parameters
- shash - session id (required)
Response
JSON_OK response
{"result":"OK","devices":[{"device":":string:","subproto":":string:","delta":integer},...]}
- devices - array of streaming devices received
- device - the streaming device name
- subproto - the stream sub-protocol description
- delta - the minimal delta time between two frames in ms
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/getStreams.json
{"result":"OK","devices":[{"device":"user_pc","subproto":"DEFLATE_JSON","delta":30000},{"device":"camera1","subproto":"RAW_THEORA","delta":400}]}
deleteRecords.json
Delete specified media records from server.
Request
The JSON object
{"shash":":string:", "records":[integer_array]}
Possible (alternative) query string https://localhost/getRecordData.json?shash=string&records=%5Binteger_array%5D
Parameters
- shash - session id (required)
- records - an array of integers, each element of which is a media record ID (required). Media record Ids can be obtained using getRecordCount.json request. if the array contains a negative number, the server in addition will delete all records that have a timestamp older than the oldest record passed with the request.
Response
JSON_OK response
JSON_BAD response
JSON_BAD response format and description of error codes
Example
The following records exist on the server:
rid
| stamp |
| 30 | 2022-02-07 12:29:32 |
| 32 | 2022-02-07 12:30:00 |
| 33 | 2022-02-07 13:00:00 |
| 34 | 2022-02-07 13:30:00 |
| 40 | 2022-02-07 14:00:00 |
| 42 | 2022-02-07 14:30:00 |
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","records":[40]}' -X POST https://localhost:8080/deleteRecords.json
{"result":"OK"}
After the request, the following records remained on the server:
rid
| stamp |
| 30 | 2022-02-07 12:29:32 |
| 32 | 2022-02-07 12:30:00 |
| 33 | 2022-02-07 13:00:00 |
| 34 | 2022-02-07 13:30:00 |
| 42 | 2022-02-07 14:30:00 |
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE=","records":[-1,34,32]}' -X POST https://localhost:8080/deleteRecords.json
{"result":"OK"}
After the last request, the following records remained on the server:
rid
| stamp |
| 33 | 2022-02-07 13:00:00 |
| 42 | 2022-02-07 14:30:00 |
heartBit.json
Sends a "heart beat" message to refresh session state. After a certain time, the server deletes sessions if they do not send messages (for details, see the article). If the client needs to maintain a background connection to the server, "heart beat" messages must be sent periodically.
Request
The JSON object
Possible (alternative) query string https://localhost/heartBit.json?name=string&shash=string
Parameters
- shash - session id (required)
Response
JSON_OK response
JSON_BAD response
JSON_BAD response format and description of error codes
Example
> curl --http2 -k -d '{"shash":"ra5PNJRgzrqpwbfw8JvHIkWuxJE="}' -X POST https://localhost:8080/heartBit.json
{"result":"OK"}
JSON_BAD message format
{"result":"BAD","code":integer}
- code - value of error code returned by server
Possible error codes
0 - NO_ERROR - no error detected
1 - UNSPECIFIED - unspecified error, can be used inside
client applications to determinate internal
client errors
2 - INTERNAL_UNKNOWN_ERROR - internal server error (server system error)
3 - DATABASE_FAIL - error inside sqlite3 engine occurred
4 - JSON_PARSER_FAIL - wrong JSON format
5 - JSON_FAIL - other handled server errors, caused by
misrepresentation of parameters inside
request
6 - NO_SUCH_SESSION - shash (session id) passed by client is
wrong or expired
7 - NO_SUCH_USER - no such account found (wrong user's name or
password)
8 - NO_DEVICES_ONLINE - no devices found
9 - NO_SUCH_RECORD - rid (record id) passed by client is wrong
or erased
10 - NO_DATA_RETURNED - the requested record inside database is
empty
11 - EMPTY_REQUEST - client sends an empty request
12 - MALFORMED_REQUEST - client sends malformed request (some
required parameters are missing or
malformed)
13 - NO_CHANNEL - the requested stream does not exist
14 - ERRORED_STREAM - the stream has errors
15 - NO_SUCH_DEVICE - device is not founded
1.9.1