JSON-RPC
JSON-RPC is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a handful of data types and commands. JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered out of order.
History
Version | Description | Dated |
---|---|---|
1.0 | Original version | 2005 |
1.1 WD | Working draft Adds named parameters, adds specific error codes, and adds introspection functions. | 2006-08-07 |
1.1 Alt | Suggestion for a simple JSON-RPC 1.1 Alternative proposal to 1.1 WD. | 2007-05-06 |
1.1 Object Specification | Object Specification Alternative proposal to 1.1 WD/1.1ALT. | 2007-07-30 |
1.2 | Proposal A later revision of this document was renamed to 2.0. | 2007-12-27 |
2.0 | Specification proposal | 2009-05-24 |
2.0 (Revised-) | Specification | 2010-03-26 |
Usage
JSON-RPC works by sending a request to a server implementing this protocol. The client in that case is typically software intending to call a single method of a remote system. Multiple input parameters can be passed to the remote method as an array or object, whereas the method itself can return multiple output data as well. (This depends on the implemented version.)
All transfer types are single objects, serialized using JSON.[1] A request is a call to a specific method provided by a remote system. It must contain three certain properties:
-
method
- A String with the name of the method to be invoked. -
params
- An Object or Array of values to be passed as parameters to the defined method. -
id
- A value of any type used to match the response with the request that it is replying to.
The receiver of the request must reply with a valid response to all received requests. A response must contain the properties mentioned below.
-
result
- The data returned by the invoked method. If an error occurred while invoking the method, this value must be null. -
error
- A specified error code if there was an error invoking the method, otherwise null. -
id
- The id of the request it is responding to.
Since there are situations where no response is needed or even desired, notifications were introduced. A notification is similar to a request except for the id, which is not needed because no response will be returned. In this case the id
property should be omitted (Version 2.0) or be null
(Version 1.0).
Examples
In these examples, -->
denotes data sent to a service (request), while <--
denotes data coming from a service. (Although <--
often is called response in client–server computing, depending on the JSON-RPC version it does not necessarily imply answer to a request).
Version 2.0
Request and response:
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
Notification (no response):
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
Version 1.1 (Working Draft)
Request and response:
--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}
Version 1.0
Request and response:
--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}
See also
- Remote procedure call (RPC)
- XML-RPC
- SOAPjr - a hybrid of SOAP and JSON-RPC
- JSON-WSP - a JSON-RPC inspired protocol with a service description specification.
- JSend specification which defines only format of response
References
External links
- Official website
- JSON-RPC Google Group discussing topics of and around the protocol
- JSON-RPC specifications, links etc.
- Official JSON-RPC 1.0 homepage (currently outdated)