The goal of a Request, Response, Event protocol is to give all messages a consistent meaningful format while defining mechanisms for remote querying.
Messages are transmitted as valid JSON-parsable strings and must conform to one of the message-formats given below.
All format-defined properties are required to be part of the resulting JSON string. If a defined property does not have an applicable value, it's value should default to null.
Implementations should NOT define/relay upon any property not defined in a format. Any non format-defined property in the message's JSON string is to be ignored by the recipient.
Messages that are nonconformant may be treated as invalid, discarded/ignored, or allowed to passed through.
A request-message is used by the sender to query a remote resource. These messages must always result in a Reply.
| Property | Type | Nullable | Description |
|---|---|---|---|
type |
String="request" |
no | Literal text request |
id* |
String |
no | A sender-generated ID |
meta |
String |
no | The resource identifier to query |
data** |
Array<any> |
no | A list of values(arguments) to pass to the resource handler |
*: The id should be unique to the connection session but may be reused once a response has been received.
**: If no values are to be provided to the resource data should be an empty array.
Upon receiving a Request, the recipiant should process the request and respond with a response-message. Responses may be transmitted in any order regardless of order in which the originating requests were received.
| Property | Type | Nullable | Description |
|---|---|---|---|
type |
String="response" |
no | Literal text response |
id |
String |
no | The id property received with the request-message |
meta |
String="ok" |
no | Literal text ok |
data |
any | yes | Resulting value from processing the query |
| Property | Type | Nullable | Description |
|---|---|---|---|
type |
String="response" |
no | Literal text response |
id |
String |
no | The id property received with the request-message |
meta |
String="error" |
no | Literal text error |
data |
String |
yes | Error message detailing why the query failed |
An event-message is used to notify the recipient of a state change. Event-messages infer the sender does not care about the actions taken by recipient as a result of receiving the message.
| Property | Type | Nullable | Description |
|---|---|---|---|
type |
String="event |
no | Literal text "event" |
id* |
String |
no | Ignored |
meta |
String |
no | Event name/Notification identifier |
data |
any | yes | The data accompanying the event |
*: To keep the formats consistent, the id parameter must be specified but its value is ignored by the recipient.