Specification - libertylocked/RestRPC GitHub Wiki

RestRPC Specification Draft

1. Overview

RestRPC (RRPC) is a client-to-client remote procedure call (RPC) platform. RRPC supports both REST and WebSocket clients. The specification is similar to JSON-RPC 2.0, with additional fields to identify the requester/responder.

There are 3 roles in the RRPC specification:

  • RRPC server ("router"): The request/response router. Server is responsible to deliver a request (submitted via either WebSocket or REST) to its intended service, and return the response back to the requester.
  • RRPC client ("requester"): The requester of a remote procedure. The origin of Request objects and the handler of Response objects.
  • RRPC service ("responder"): The origin of Response objects and the handler of Request objects.

2. Request object

An RPC call is represented by sending a Request object to a Server. The Request object has the following members:

string TID
  • A string specifying the receiver of the Request object.
  • This should be the ID of the service that the Response object for this Request is expected from.
string Method
  • A string containing the name of the method to be invoked.
object[] Params
  • An array that holds the parameter values to be used during the invocation of the method.
string ID
  • A string identifier established by the Client. If this field is not included, it is assumed to be a notification.
  • The Server MUST reply with the same value in the Response object if included. This memer is used to correlate the context between the two objects.

2.1 Notification

A Notification is a Request object without an ID member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Service MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params","Internal error").

2.2 Parameter Structures

Unlike JSON-RPC 2.0, parameters for the RPC call MUST be an array, containing the values in the Service expected order.

2.3 Request object from Server to Service

Once a Request object is submitted to the Server, the Server attaches an extra field in the Request object.

string RID
  • A string identifier that identifies the Client.
  • This field is set by the Server. In the case of REST, RID is unique per call. In the case of WebSocket, RID is unique per WebSocket session.
  • The Service MUST reply with the same value in the Response object. This member is used for the Server to route the Response back to its Client requester.

The Server will then wrap the Request object in a Server-to-Service message, and send to the Service identified in TID. A Server-to-Service message has the following members:

string Header
  • The header is currently unused
RequestObject Data
  • The wrapped Request object, as defined in section 2
  • The Request object MUST contain the RID attached by the Server
  • The TID field of the Request object SHOULD be omitted by the Server

3. Response object

When a RPC call delivered to the Service, the Service MUST reply with a Response, except for in the case of Notifications. The response is expressed as a single JSON Object, with the following members:

object Result
  • This member is REQUIRED on success.
  • The value of this member is determined by the method invoked on the Service
ErrorObject Error
  • This member is REQUIRED on error
  • This member MUST NOT exist if there was no error triggered during invocation
  • The value for this member MUST be an Object as defined in section 3.1
string ID
  • This member is REQUIRED
  • It MUST be the same as the value of the id member in the Request Object.

Unlike JSON-RPC 2.0, Result is NOT REQUIRED to be null if there was an error.

3.1 Error object

When an RPC call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

int Code
  • A Number that indicates the error type that occurred.
string Message
  • A String providing a short description of the error.
  • The message SHOULD be limited to a concise single sentence.
object Data
  • A Primitive or Structured value that contains additional information about the error.
  • This may be omitted.

3.2 Response object from Service to Server

Before a Response object is returned to the Server from a Service, the Service must attach an extra field in the Response object

string RID
  • A string identifier that identifies the requester Client.
  • This field is MUST match the RID field of the corresponding Request object the Service received from the server in a Server-to-Service message.

The Service will then wrap the Response object in a Service-to-Server message, and send to the Server. The Service-to-Server message has the following members:

string Header = ""
  • This field SHOULD be omitted
  • If this field is included, it MUST be an empty string
ResponseObject Data
  • The wrapped Response object, as defined in section 3
  • The Response object MUST contain the RID field

4 Examples

Syntax:

C-->S data sent to Server from Client
S-->V data sent to Service from Server
S<--V data sent to Server from Service
C<--S data sent to Client from Server

RPC call with positional parameters:

C-->S: {"TID":"MyService", "Method":"echo", "Params":["hello","world"], "ID":"1"}
S-->V: {"Header":"", "Data":{"Method":"echo", "Params":["hello","world"], "ID":"1", "RID":"0b5659c8-20a3-484b-b8a5-28bf95944bf7"}}
V-->S: {"Header":"", "Data":{"Result":["hello","world"], "ID":"1", "RID":"0b5659c8-20a3-484b-b8a5-28bf95944bf7"}}
S-->C: {"Result":["hello","world"], "ID":"1"}