.. -*- 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 } }