1.1   Thoughts about RPC

In my option, RPC consists of several independent parts:

1. data structure (how requests/responses/errors look like)
2. serializer (i.e. JSON, XML, URI, ...)
3. transport (i.e. unix domain socket, tcp/ip, http)
4. proxy/dispatcher

Unfortunately, these parts are often not treated as independent, which results in unnecessary complex results [1]. A RPC-specification should only define point 1 ("data structure"), and tell the user which serialization to use [2].

1.2   Structure of this Document

The following sections mostly use the same headlines (and often same numbers) as the 1.1WD, if possible.

1.3   TODO

• should a note on an optimal "Member Sequence" and the possible optimization be added?
• should something like class-hinting (like in JSON-RPC 1.0), or references (for cyclic objects etc.) be defined?
• error-messages: timeout!
• should Object extensions (like in 1.1WD Object Extensions) be defined?
• ...

see also the may TODO tags all over this document.

2.1   Differences from Version 1

The most important differences are:

• named parameters added (like in 1.1WD)
• "version" added (like in 1.1WD)
• "id" now optional (like in 1.1WD)
• "kwparams" added
• notifications removed (like in 1.1WD)
• added error object
• added system services

2.2   Differences from 1.1WD

The most important differences are:

• Transport:

  1.1WD requires HTTP.

  This specification does not rely on any specific transport, so you can use i.e. unix domain sockets, tcp/ip, http, or even letters or avian carriers. This removes much of the complexity of the 1.1WD.

• HTTP:

  Nevertheless, if you want to use http, an appendix recommends how to use JSON-RPC over HTTP: simply tunnel JSON-RPC through HTTP.

  HTTP then doesn't need to know anything about JSON-RPC. And I don't think that it's reasonable to i.e. convert JSON-RPC-errors to HTTP errors.

  HTTP GET is discouraged. And if you really want to use HTTP GET, you should use a small wrapper, which converts HTTP GET calls to json-rpc.

  The "User-Agent" header is not explicitly required anymore, because it does not provide any information for JSON-RPC.

• Named and Positional Parameters, Null parameters:

  1.1WD allows mixed named and positional parameters, which requires much more complicated servers and clients and adds some ambiguity. It also says that "Null ... as the value of any parameter ... MUST be taken to mean that the parameter is not being supplied for the call".

  This specification allows either named or positional parameters, and it also optionally allows but discourages the use of both in one call. It also uses a separate objects for named and positional parameters.

  "Null" is no special value, and a parameter-value of "Null" simply means that the parameter should be "Null".

• Member Sequence:

  1.1WD: the members of the JSON-RPC-object SHOULD be in a specific order, and allows the server to refuse requests which do not stick to this order.

  This is removed in this specification.

• Procedure Call Parity, Call Approximation:

  Removed in this specification. A Service must be called exactly as specified.

  (Things like "Call Approximation" and other magic are considered harmful, and may result in unexpected results. It's much better to require the client to say exactly what he wants than having a server which guesses.)

• Error Object:

  The "name" member was removed, because it does not provide any information. The error-code is no longer limited to 100-999, so that i.e. the xmlrpc-error-codes can be used.

• Services, Service Description, Parameter and Return Type Strings:

  service.description is now optional. Additional optional system-services were added (mainly those from xmlrpc).

  The "Parameter and Return Type Strings" now SHOULD be used (instead of "MAY"), and it is not allowed to supply the Null value for all parameters.

• Service, Procedure and Parameter Names:

  Added underscore ("_") to, and removed hypen ("-") from the recommended characters. Additionally, added period (".") for methods, and everything is defined as case-sensitive.

• Object Extensions:

  This was removed in this specification.

• Multicall:

  This was added in this specification.

6.1   Named and Positional Parameters

Parameters for a procedure call can be identified by their name or position. The name and position of a parameter is defined by the formal argument list of the target procedure.

A client can specify parameters:

• by-position: "params" contains the parameters in the right order, "kwparams" is omitted. This is like JSON-RPC 1.0.

  Every JSON-RPC implementation MUST support this.

• by-name: "kwparams" contains the parameter-names and its values, "params" is omitted. The names MUST match exactly (including in case) the names defined by the formal arguments.

  Every JSON-RPC implementation SHOULD support this.

• mixed: The usage of both "params" and "kwparams" in one call is discouraged. Nevertheless, a JSON-RPC implementation MAY support this. Then, if a parameter is both given as named and positional parameter, an error MUST be returned.

  If the implementation does not support both in one call, it MUST return an error if called with both.

6.2   Call examples

--> data sent to service
<-- data coming from service

Suppose a remote procedure called sum that defines three formal arguments called a, b and c. Suppose further that a comes first in the argument list, b second and c third, as in "sum(a,b,c)". The following examples show how this procedure can be called.

--> { "version" : "1.1", "method" : "sum", "kwparams" : { "a" : 12, "b" : 34, "c" : 56 } }

--> {
    "version"  : "1.1",
    "method"   : "sum",
    "kwparams" : { "b" : 34, "c" : 56, "a" : 12 }
    }

--> {"version" : "1.1", "method"  : "sum", "params"  : [ 12, 34, 56 ] }

--> { "version": "1.1", "method": "sum", "params": [12,34], "kwparams":{"c": 56} }

7.1   Error Object

When a remote procedure call fails, the Procedure Return object MUST contain the error member whose value is a JSON Object with the following members:

code

REQUIRED. A Number value that indicates the actual error that occurred. This MUST be an integer.

message

REQUIRED. A String value that provides a short description of the error. The message SHOULD be limited to a concise single sentence.

error

OPTIONAL. A JSON Null, Number, String or Object value that carries custom and application-specific error information. Error objects MAY be nested using this property.

The following table lists the error codes defined by this specification:

7.2   Response Examples

Suppose the example from Call Examples. The response to all these calls on success would be:

<-- { "version" : "1.1", "result" : 102 }

And here's a possible response on error:

<-- {
    "version" : "1.1",
    "error" : {
         "code" : 123,
         "message" : "An error occurred parsing the request object.",
         "error" : {
             "message" : "Bad array",
             "at" : 42,
             "text" : "{\"id\":1,\"method\":\"sum\",\"params\":[1,2,3,4,5}"

             }
         }
    }

8.1   Parameter and Return Type Strings

The type member of the Procedure Parameter Description SHOULD be one of the following String values:

"bit"

Boolean

"num"

Number

"str"

String

"arr"

Array

"obj"

Object

"any"

Boolean, Number, String, Array or Object

"nil"

None (valid only for procedure return type)

If another String value is found then it MUST be treated the same as "any".

The "nil" string MUST NOT be used to describe the type of a procedure's formal argument. Rather, it is strictly reserved to denote the return type of a procedure that is not expected to produce a result. In other words, the result member of the Procedure Return object resulting from a call to such procedure is not interesting because it will always be the Null value.

10.1   Multicall

There is a special method called "system.multicall", like in XMLRPC. This method takes the single calls as positional parameters (in "params"). The result is a list of the single-call results.

Call Example:

--> { "version":"1.1", "method":"system.multicall", "params":
      [{ "version":"1.1", "method":"sum", "params":{"a":1,"b":1} },
       { "version":"1.1", "method":"sum", "params":{"a":2,"b":2} },
       { "version":"1.1", "method":"sum", "params":{"a":3,"b":3} }]
    }

Return Example on success:

<-- { "version":"1.1", "result":
     [{ "version":"1.1", "result":2 },
      { "version":"1.1", "result":4 },
      { "version":"1.1", "result":6 }]
    }

Return Example with some errors:

<-- {"version":"1.1", "result":
    [{"version":"1.1", "error":{"code":..., "message":"..."}},
     {"version":"1.1", "result":4},
     {"version":"1.1", "error":{"code":..., "message":"..."}}]
   }

Return Example if the multicall itself fails:

<-- {"version":"1.1", "error":{"code":..., "message":"Parse error"}}

11.1   Unix Domain Sockets

This is straight-forward: open a socket and send/receive the data.

11.2   TCP/IP Sockets

This is straight-forward: open a socket and send/receive the data.

11.3   HTTP

If you want to use HTTP, simply tunnel JSON-RPC through HTTP with Content-Type "application/json".

POST /myservice HTTP/1.1
User-Agent: Wget/1.6
Host: www.example.com
Content-Type: application/json
Content-Length: ...
Accept: application/json

{
     "version"  : "1.1",
     "method"   : "sum",
     "kwparams" : { "b" : 34, "c" : 56, "a" : 12 }
}

HTTP/1.1 200 OK
Connection: close
Content-Length: ...
Content-Type: application/json
Date: Sat, 08 Jul 2006 12:04:08 GMT

{
    "version" : "1.1",
    "result"  : 102
}

HTTP/1.1 200 OK
Connection: close
Content-Length: ...
Content-Type: application/json
Date: Sat, 08 Jul 2006 12:04:08 GMT

{
    "version" : "1.1",
    "error" : {
        "code" : 123,
        "message" : "An error occurred parsing the request object.",
        "error" : {
            "message" : "Bad array",
            "at" : 42,
            "text" : "{\"id\":1,\"method\":\"sum\",\"params\":[1,2,3,4,5}"}
        }
    }
}