========================= DRAFT: JSON-RPC over HTTP ========================= **This is a working draft!** :Author: Jeffrey Damick and JSON-RPC Working Group; reformatted by Roland Koebler :Date: 2008-01-15 .. contents:: **Table of Contents** :backlinks: none .. sectnum:: ----- Preface ======= "*JSON-RPC is a lightweight remote procedure call protocol. It's designed to be simple!*" [JSON-RPC 1.0] The goal of this document is to propose a JSON-RPC 2.0 extension to specify. For mailing list location: `JSON-RPC Google Group`_ .. _JSON-RPC Google Group: http://groups.google.com/group/json-rpc?hl=en Changelog ========= - 2008-01-15: Initial creation Specification ============= Overview -------- JSON-RPC over `HTTP`_ is an extension to the `JSON-RPC 2.0`_ specification. .. _HTTP: http://www.ietf.org/rfc/rfc2616.txt .. _JSON-RPC 2.0: jsonrpc20.html Conventions ----------- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC 2119`_. Since JSON-RPC uses JSON, it shares the same type system as JSON (see http://www.json.org or `RFC 4627`_). Whenever this document refers to any JSON type, the first letter is always capitalized: Object, Array, String, Number, True, False, Null. Clients are the origin of Request objects. Servers are the origin of Response objects. .. _RFC 2119: http://www.ietf.org/rfc/rfc2119.txt .. _RFC 4627: http://www.ietf.org/rfc/rfc4627.txt HTTP Header ----------- Requirements: Regardless of whether a remote procedure call is made using HTTP GET or POST, the HTTP request message MUST specify the following headers: - *Content-Type* SHOULD be ``application/json-rpc`` but MAY be ``application/json`` or ``application/jsonrequest``. - The *Content-Length* MUST be specified and correct according to the guidelines and rules laid out in the `HTTP`_ specification, Section 4.4, Message Length. - The *Accept* MUST be specified and SHOULD read ``application/json-rpc`` but MAY be ``application/json`` or ``application/jsonrequest``. POST ---- Post body contains the Object request specified in `JSON-RPC 2.0 Section 4`_. Response to a Post contains the Object response specified in `JSON-RPC 2.0 Section 5`_. Responses with a null error will result in an HTTP 200 Status Code, while non-null error codes will be mapped to HTTP Status code as specified in the `Errors`_ section. Example:: --> POST /ENDPOINT HTTP/1.1 Host: ... Content-Type: application/json-rpc Content-Length: ... {"method": "sum", "params": {"a":3, "b":4}, "id":0} <-- HTTP/1.1 200 OK ... Content-Type: application/json-rpc {"result": 7, "error": null, "id": 0} --> POST /ENDPOINT HTTP/1.1 Host: ... Content-Type: application/json-rpc Content-Length: ... {"method": "test", "params": [], "id": 0} ... .. _JSON-RPC 2.0 Section 4: jsonrpc20.html#request-object .. _JSON-RPC 2.0 Section 5: jsonrpc20.html#response-object .. _Errors: jsonrpc20.html#error-object GET --- - MUST be either Array or Object parameters [#]_ - Keep in mind that some old clients and proxies have issues wth URI lengths over 255 bytes [#]_ - HTTP POST is the preferred method for sending JSON-RPC - Parameters must be `encoded`_ Example:: http://?method=¶ms=&id=1 .. _encoded: #encoded-parameters .. [#] Per `JSON-RPC 2.0`_ specification .. [#] http://classicasp.aspfaq.com/forms/what-is-the-limit-on-querystring/get/url-parameters.html Encoded Parameters ~~~~~~~~~~~~~~~~~~ Encoding Steps: 1. `Base 64`_ param value 2. `URL Encoded`_ Base 64 param value .. _Base 64: http://tools.ietf.org/html/rfc4648#section-4 .. _URL Encoded: http://www.blooberry.com/indexdot/html/topics/urlencoding.htm Pre-Encoded Params:: http://?method=sum¶ms={"a":3,"b":4}&id=2 http://?method=sum¶ms=[3,4]&id=1 Encoded Request:: http://?method=sum¶ms=eyJhIjozLCJiIjo0fQ%3D%3D&id=2 http://?method=sum¶ms=WzMsNF0%3D&id=1 Response Codes -------------- Success ~~~~~~~ For non-notification requests [#]_ including system procedures using `POST`_ or `GET`_ MUST indicate a success response using `HTTP`_ status code: 200. However, for `JSON-RPC 2.0 Notification`_ requests, a success response MUST be an HTTP status code: 204. .. _POST: #post .. _GET: #get .. _JSON-RPC 2.0 Notification: jsonrpc20.html#notification .. [#] `JSON-RPC 2.0 Section 4`_ Errors ~~~~~~ =============== =============== =================== HTTP Status code message =============== =============== =================== 500 -32700 Parse error. 400 -32600 Invalid Request. 404 -32601 Method not found. 500 -32602 Invalid params. 500 -32603 Internal error. 500 -32099..-32000 Server error. =============== =============== =================== For more details on error codes see table in `JSON-RPC 2.0 Section 5.1`_. For more details on HTTP Status codes, refer to `HTTP`_ section 6.1.1. .. _JSON-RPC 2.0 Section 5.1: jsonrpc20.html#error-object ---- Copyright (C) 2008 by JSON-RPC Working Group This document and translations of it may be used to implement JSON-RPC over HTTP, it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way. The limited permissions granted above are perpetual and will not be revoked. This document and the information contained herein is provided "AS IS" and ALL WARRANTIES, EXPRESS OR IMPLIED are DISCLAIMED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.