JSON-RPC

JSON-RPC is a remote procedure call protocol encoded in JSON.

Saplo API 1.0 is based on JSON-RPC version 1.1 and Saplo API 2.0 is based on the specification JSON-RPC version 2.0. Though some of the parts in the specification is different from our API. Below is stated how Saplo API works using JSON-RPC (some text and descriptions are copied from the specification site.).

Requests

A request is made by sending a json formatted string to the URI endpoint. The request should consist of following members:

method - (required) A String containing the name of the method to be invoked.

params - A Structured value that holds the parameter values to be used during the invocation of the method. This member may be omitted if no params is required.

id - An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification and the server will not return any response. The Server replies with the same value in the Response object if included. This member is used to correlate the context between the two objects.

jsonrpc - A String specifying the version of the JSON-RPC protocol.

{
    "jsonrpc": "2.0",
    "method": "auth.accessToken",
    "params": {"api_key": "myapikey", "secret_key": "mysecretkey"},
    "id": "my-id-001"
}

Response

A successful response is a JSON-object with two fields.

id - The id for asyncronous requests that was sent along with the request.

result - The result.

{
    "jsonrpc": "2.0",
    "result": {"access_token": "Result from API"},
    "id": "my-id-001"
}

Error Response

error - An error object containing values for code and msg.

id - The id for asyncronous requests that was sent along with the request.

{
    "jsonrpc": "2.0",
    "error": {"code": 1101, "msg":"API-key and/or Secret-key incorrect"},
    "id": "my-id-001"
}

Batch Requests

We support batch calls as stated in the JSON-RPC 2.0 specification. See "Differences from Specification" for Saplo specific implementations.

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
        {"foo": "boo"},
        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": ["hello", 7]},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found."}, "id": "5"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

Differences from Specification

  • Error Message: Instead of sending back a param named "message" it is named "msg".
  • Saplo API don't require the param "jsonrpc".
  • The original JSON-RPC Specification handles requests with a missing "id" parameter as a notification and does not send back responses for such requests. This is not the case for Saplo API, we are always sending back a response.