JSON-RPC

From Seo Wiki - Search Engine Optimization and Programming Languages
Jump to navigationJump to search

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. In contrast to XML-RPC or SOAP, it allows for bidirectional communication between the service and the client, treating each more like peers and allowing peers to call one another or send notifications to one another. It also allows multiple calls to be sent to a peer which may be answered out of order.

A JSON invocation can be carried on an HTTP request where the content-type is application/json[1]. Besides using HTTP for transport, one may use TCP/IP sockets. Using sockets, one can create much more responsive web applications with JSON-RPC, compared to polling data from a service with JSON-RPC over HTTP.

History

Version Description Dated
1.0 Original version Currently considered official according to [2] 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.2 Proposal A later revision of this document was renamed to 2.0. 2007-12-27
2.0 Specification proposal 2009-05-24

Examples

In these examples, --> denotes data sent to a service (request), while <-- denotes data coming from a service. (Although this direction often is called response in client-server computing, depending on the JSON-RPC version it does not necessarily imply answer to a request).

Version 1.0

A simple request and response:

--> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

This example shows parts of a communication from an example chat application. The chat service sends notifications for each chat message the client peer should receive. The client peer sends requests to post messages to the chat and expects a positive reply to know the message has been posted.[3]

...
--> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
<-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
--> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
<-- {"method": "userLeft", "params": ["user3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

Version 1.1 (Working Draft)

The format of the contents of a request might be something like that shown below:

{ 
"version": "1.1", 
"method": "confirmFruitPurchase", 
"id": "194521489", 
"params": [ 
    [ "apple", "orange", "pear" ], 
    1.123 
]
}

The format of a response might be something like this:

{ 
"version": "1.1", 
"result": "done", 
"error": null, 
"id": "194521489"
}

Version 2.0 (Specification Proposal)

Procedure Call with positional parameters:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}
--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

Procedure Call with named parameters:

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

Notification:

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}

Procedure Call of non-existent procedure:

--> {"jsonrpc": "2.0", "method": "foobar", "id": 10}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": 10}

Procedure Call with invalid JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz"]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

Procedure Call with invalid JSON-RPC:

--> [1,2,3]
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}
--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}

Implementations


The original official homepage[4] has links to more implementations.

See also

References

External links