This document uses the definition of resource, model, collection, value, service, client, and gateway as described in the RES Protocol specification.
The RES-Client protocol is used in communication between the client and the gateway.
A core concept in the RES-Client protocol is the subscriptions. A client may subscribe to resources by making subscribe requests with the unique resource ID, or when creating a new resource using new request.
A resource may be subscribed to directly or indirectly. Any reference to subscription, or a resource being subscribed to, in this document should be interpreted as both direct and indirect subscriptions, unless specified.
The client will receive events on anything that happens on a subscribed resource. A subscription lasts as long as the resource has direct or indirect subscriptions, or when the connection to the gateway is closed.
The resource that is subscribed to with a subscribe request, or created with a new request will be considered directly subscribed.
It is possible to make multiple direct subscriptions on a resource. It will be considered directly subscribed until an equal number of unsubscribe requests has been made.
A resource that is referred to with a resource reference by a directly subscribed resource, or by an indirectly subscribed resource, will be considered indirectly subscribed. Cyclic references where none of the resources are directly subscribed will not be considered subscribed.
Any request or event resulting in new subscriptions will contain a set of resources that contains any subscribed resource previously not subscribed by the client.
The set is grouped by type, models, collections, and errors. Each group is represented by a key/value object where the key is the resource ID, and the value is the model, collection, or error.
Example
{
"models": {
"messageService.message.1": {
"id": 1,
"msg": "foo"
},
"messageService.message.2": {
"id": 2,
"msg": "bar"
}
},
"collections": {
"messageService.messages": [
{ "rid": "messageService.message.1" },
{ "rid": "messageService.message.2" },
{ "rid": "messageService.message.3" }
]
},
"errors": {
"messageService.message.3": {
"code": "system.notFound",
"message": "Not found"
}
}
}
A connection ID tag is a specific string, "{cid}" (without the quotation marks), that may be used as part of a resource ID.
The gateway will replace the tag with the clients actual connection ID before passing any request further to the services.
Any event on a resource containing a connection ID tag will be sent to the client with the tag, never with the actual connection ID.
Example
authService.user.{cid} - Model representing the user currently logged in on the connection.
The client RPC protocol is a variant of the JSONRPC 2.0 specification, with the RES gateway acting as server. It differs in the following:
- WebSockets SHOULD be used for transport
- Request object SHOULD NOT include the
jsonrpcproperty - Request object's
methodproperty MUST be a valid request method - Response object does NOT contain
jsonrpcproperty - Response object does NOT require the
resultproperty - Error object's MUST be a valid error object, where the
codeproperty MUST be a string. - Batch requests are NOT supported
- Client notifications are NOT supported
- Server may send event objects
An error object has following members:
code
A dot-separated string identifying the error.
Custom errors SHOULD begin with the service name.
MUST be a string.
message
A simple error sentence describing the error.
MUST be a string.
data
Additional data that may be omitted.
The value is defined by the service.
It can be used to hold values for replacing placeholders in the message.
There are a number of predefined errors.
| Code | Message | Meaning |
|---|---|---|
system.notFound |
Not found | The resource was not found |
system.invalidParams |
Invalid parameters | Invalid parameters in method call |
system.internalError |
Internal error | Internal error |
system.methodNotFound |
Method not found | Resource method not found |
system.accessDenied |
Access denied | Access to a resource or method is denied |
system.timeout |
Request timeout | Request timed out |
system.noSubscription |
No subscription | The resource has no direct subscription |
Clients sends request to the gateway and the gateway responds with a request result or a request error. The request's method property contains the request method, and the params property contains the parameters defined by the services for requests of type call and auth.
A request method is a string identifying the type of request, which resource it is made for, and in case of call and auth requests which resource method is called.
A request method has the following structure:
<type>.<resourceID>.<resourceMethod>
- type - the request type. May be either
subscribe,unsubscribe,get,call,auth, ornew. - resourceID - the resource ID.
- resourceMethod - the resource method. Only used for
callorauthtype requests. If not included, the separating dot (.) must also not be included.
Examples
subscribe.userService.users- Subscribe request of a collection of userscall.userService.user.42.set- Call request to set properties on a usernew.userService.users- New request to create a new userauth.authService.login- Authentication request to login
method
subscribe.<resourceID>
Subscribe requests are sent by the client to subscribe to a resource.
The request has no parameters.
models
Resource set models.
May be omitted if no new models were subscribed.
collections
Resource set collections.
May be omitted if no new collections were subscribed.
errors
Resource set errors.
May be omitted if no subscribed resources encountered errors.
An error response will be sent if the resource couldn't be subscribed to.
Any resource reference that fails will not lead to an error response, but the error will be added to the resource set errors.
Unsubscribe requests are sent by the client to unsubscribe to a previous made direct subscription.
The resource will only be considered unsubscribed when there are no more direct or indirect subscriptions.
method
unsubscribe.<resourceID>
The request has no parameters.
The result has no payload.
An error response with code system.noSubscription will be sent if the resource has no direct subscription.
Get requests are sent by the client to get a resource without making a subscription.
method
get.<resourceID>
The request has no parameters.
models
Resource set models.
May be omitted if no new models were retrieved.
collections
Resource set collections.
May be omitted if no new collections were retrieved.
errors
Resource set errors.
May be omitted if no retrieved resources encountered errors.
An error response will be sent if the resource couldn't be retrieved.
Any resource reference that fails will not lead to an error response, but the error will be added to the resource set errors.
Call requests are sent by the client to invoke a method on the resource.
method
call.<resourceID>.<resourceMethod>
The request parameters are defined by the service.
The result payload is defined by the service.
An error response will be sent if the method couldn't be called, or if the method was called, but an error was encountered.
Auth requests are sent by the client to authenticate the client connection.
method
auth.<resourceID>.<resourceMethod>
The request parameters are defined by the service.
The result payload is defined by the service.
An error response will be sent if the method couldn't be called, or if the authentication failed.
New requests are sent by the client to create a new resource.
The newly created resource will get a direct subscription, and will be sent to the client in the resource set.
method
new.<resourceID>
The request parameters are defined by the service.
For new models, the parameters are usually an object containing the named properties and values of the model.
For new collections, the parameters are usually an ordered array containing the values of the collection.
rid
Resource ID of the created resource.
models
Resource set models.
May be omitted if no new models were subscribed.
collections
Resource set collections.
May be omitted if no new collections were subscribed.
errors
Resource set errors.
May be omitted if no subscribed resources encountered errors.
An error response will be sent if the resource could not be created, or if an error was encountered retrieving the newly created resource.
The gateway sends event objects to describe events on resources currently subscribed to by the client.
RES protocol does not guarantee that all events sent by the service will reach the client. It only guarantees that the events sent on a resource will describe the modifications required to get the resource into the same state as on the service.
An event object has the following members:
event
Identiying which resource the event occurred on, and the type of event.
It has the following structure:
<resourceID>.<eventName>
MUST be a string.
data
Event data. The payload is defined by the event type.
Change events are sent when a model's properties has been changed.
Will result in new indirect subscriptions if changed properties contain resource references previously not subscribed.
Change events are only sent on models.
event
<resourceID>.change
data
A key/value object describing the properties that was changed. Each property contains the new value or a delete action.
Unchanged properties may be included and SHOULD be ignored.
models
Resource set models.
May be omitted if no new models were subscribed.
collections
Resource set collections.
May be omitted if no new collections were subscribed.
errors
Resource set errors.
May be omitted if no subscribed resources encountered errors.
{
"event": "myService.myModel.change",
"data": {
"myProperty": "New value",
"unusedProperty": { "action": "delete" }
}
}
A delete action is a JSON object used when a property has been deleted from a model. It has the following signature:
{ "action": "delete" }
Add events are sent when a value is added to a collection.
Will result in one or more new indirect subscriptions if added value is a resource references previously not subscribed.
Add events are only sent on collections.
event
<resourceID>.add
data
Add event object.
The add event object has the following parameters:
idx
Zero-based index number of where the value is inserted.
value
Value that is added.
models
Resource set models.
May be omitted if no new models were subscribed.
collections
Resource set collections.
May be omitted if no new collections were subscribed.
errors
Resource set errors.
May be omitted if no subscribed resources encountered errors.
{
"event": "userService.users.add",
"data": {
"idx": 12,
"value": { "rid": "userService.user.42" },
"models": {
"userService.user.42": {
"id": 42,
"firstName": "Jane",
"lastName": "Doe"
}
}
}
}
Remove events are sent when a value is removed from a collection.
Remove events are only sent on collections.
event
<resourceID>.remove
data
Remove event object.
The remove event object has the following parameter:
idx
Zero-based index number of the value being removed.
{
"event": "userService.users.remove",
"data": {
"idx": 12,
}
}
Custom events are defined by the services, and may have any event name except change, add, remove, unsubscribe and reaccess.
Custom events MUST NOT be used to change the state of the resource.
event
<resourceID>.<eventName>
data
Payload is defined by the service.
Unsubscribe events are sent by the gateway when subcription access to a resource is revoked. Any direct subscription to the resource are removed.
The resource may still have indirect subscriptions, in which case the resource is still considered subscribed. Otherwise, the resource is no longer considered subscribed.
event
<resourceID>.unsubscribe
data
Unsubscribe event object.
The unsubscribe event object has the following parameter:
reason
Error object describing the reason for the event.
{
"event": "messageService.messages.unsubscribe",
"data": {
"reason": {
"code": "system.accessDenied",
"message": "Access denied"
}
}
}