.. -*- coding: utf-8 -*-
..
rest2web header
restindex
page-title: simple is better - JSON-RPC 2.0 Transport: HTTP
crumb: JSON-RPC 2.0 Transport: HTTP
page-description:
JSON-RPC 2.0 Transport: HTTP
/description
tags: simple RPC, JSON, json-rpc, JSON-RPC 2.0, transport, HTTP, HTTPS
initialheaderlevel: 2
format: rest
encoding: utf-8
output-encoding: None
file: transport_http.txt
/restindex
uservalues
blockquote:
linksource:
site_copyright: webmaster(at)simple-is-better(dot)org
/uservalues
============================
JSON-RPC 2.0 Transport: HTTP
============================
:Status: **proposal/draft**
:Date: 2013-05-10
:Author: Roland Koebler
.. contents:: **Table of Contents**
:backlinks: none
.. sectnum::
-----
JSON-RPC can be simply tunneled through HTTP or HTTPS.
:SeeAlso: HTTP specification (`RFC 2616`_)
.. _RFC 2616: http://www.ietf.org/rfc/rfc2616.txt
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.)
.. _JSON-splitter: transport_sockets.html#pipelined-requests-responses-json-splitter
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``.
.. _length: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.4
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
}
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¶ms=%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¶ms=%7B%27a%27%3A+3%2C+%27b%27%3A+4%7D&id=2
.. _safe and idempotent methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1
.. _HTTP Section 9.1, Safe and Idempotent Methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1
.. _URL-encoded: http://en.wikipedia.org/wiki/URL-encoding
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
}
}