1   pipelined Requests/Responses

By default, every HTTP-message contains only a single JSON-RPC object.

But high-performance servers MAY allow several concatenated JSON-RPC Requests in a single HTTP message by using e.g. a JSON-splitter, and MAY then return concatenated Responses.

(Note that this has nothing to do with HTTP/1.1 pipelining; HTTP/1.1 pipelining is not usable for JSON-RPC, since pipelining should not be used for HTTP POST requests.)

2   POST Request

A HTTP POST request MUST specify the following headers:

• Content-Type: MUST be application/json.
• Content-Length: MUST contain the correct length according to the HTTP-specification.
• Accept: MUST be application/json.

Of course, additional HTTP-features and -headers (e.g. Authorization) can be used.

The Request itself is carried in the body of the HTTP message.

Example:

POST /myservice HTTP/1.1
Host: rpc.example.com
Content-Type: application/json
Content-Length: ...
Accept: application/json

{
    "jsonrpc": "2.0",
    "method": "sum",
    "params": { "b": 34, "c": 56, "a": 12 },
    "id": 123
}

3   GET Request

HTTP GET is not recommended for JSON-RPC, and JSON-RPC servers usually don't implement it.

HTTP GET is not really suited for RPC, since HTTP GET is only allowed for safe and idempotent methods. Additionally, HTTP GET may be cached, needs some special URL-encoding, partly has problems with lengths over 255 bytes, and usually uses a flat list of variables, whereas JSON-RPC uses nested datastructures.

Nevertheless, the following defines how it can be done. But note that:

• Often, it's better to use HTTP POST.
• Only procedures that are considered safe and idempotent MAY be invoked using HTTP GET (according to HTTP Section 9.1, Safe and Idempotent Methods). Calling other procedures via HTTP GET SHOULD result in an error.
• Keep in mind that HTTP GET requests may be cached! So, HTTP GET requests may not even reach the RPC-server.
• Some old clients and proxies have issues with URI lengths over 255 bytes.
• URL-encoding may not work for all characters; especially non-ISO-8859-1-characters may be problematic.
• If you really need HTTP GET, it's probably better to write a small RESTful wrapper around your JSON-RPC-server!

A HTTP GET request message uses the JSON-RPC-members as query-fields in the URL, and the values SHOULD be URL-encoded. The id field always has to be considered as string.

Example:

{"jsonrpc": "2.0", "method": "sum", "params": [3, 4], "id": "1"}
->
http://rpc.example.com/myservice?jsonrpc=2.0&method=sum&params=%5B3%2C4%5D&id=1

{"jsonrpc": "2.0", "method": "sum", "params": {"a": 3, "b": 4}, "id": "2"}
->
http://rpc.example.com/myservice?jsonrpc=2.0&method=sum&params=%7B%27a%27%3A+3%2C+%27b%27%3A+4%7D&id=2

4   Response

The HTTP response MUST specify the following headers:

• Content-Type: MUST be application/json
• Content-Length: MUST contain the correct length according to the HTTP-specification.

The status code SHOULD be:

200 OK

for responses (both for Response and Error objects)

204 No Response / 202 Accepted

for empty responses, i.e. as response to a Notification

307 Temporary Redirect / 308 Permanent Redirect

for HTTP-redirections (note that the request may not be automatically retransmitted)

405 Method Not Allowed

if HTTP GET is not supported: for all HTTP GET requests

if HTTP GET is supported: if the client tries to call a non-safe/non-indempotent method via HTTP GET

415 Unsupported Media Type

if the Content-Type is not application/json

others

for HTTP-errors or HTTP-features outside of the scope of JSON-RPC

The Response (both on success and error) is carried in the HTTP body.

Example on Success:

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

{
    "jsonrpc": "2.0",
    "result": 102,
    "id": 5
}

Example on Error:

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

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "Invalid Request.",
        "data": "'method' is missing"
        },
    "id": 6
    }
}