Genii Weblog
Quick primer on JSON-RPC
Fri 14 Aug 2020, 12:20 PM
Tweetby Ben Langhinrichs
Over the next few weeks, I will be demonstrating our new Exciton Boost product, which combines a high fidelity REST API and a powerful JSON-RPC API. This is just a quick primer to explain how JSON-RPC works for those unfamiliar with it.
When people talk about web APIs, they tend to think first about REST APIs. REST APIs are straightforward and recognizable, usually using JSON or XML as the payload (i.e., the stuff that will get shoved into or yanked out of the remote system), and always using HTTP as the transport mechanism. Let's assume that you either know what a REST API is or can utilize those handy dandy search engines if you are curious.
Leaving aside exactly how a REST API works and what it looks like, a core concept is that data transfer is easy and aligns well with CRUD (Create/Read/Update/Delete) operations. The programmatic effort of doing something with the data is left to the client. This makes REST APIs simple and clean, but it can make the client app more complex and lead to a lot of data going back and forth, It also means that data has to leave the server to be processed. Attempting to force actions that will happen on the server into a REST API means ignoring concepts such as resources or forcing the limited HTTP verbs to do stuff they aren't supposed to.
An alternative to the REST API is the RPC (Remote Procedure Call). This is a much older concept, but also much more wide open. The client sends instructions to the server for the server to do processing. When you tell Notes to do something to a Domino database, it is actually sending NRPC (Notes Remote Procedure Calls) to the Domino server. In the web world, there are many custom APIs, but a growing number adhere to the JSON-RPC standard.
JSON-RPC is built upon the concept of methods. It is not tied to HTTP, though it is often used with HTTP or gRPC. In either case, the request is formatted as a JSON value with either a single request object or an array of request objects. A sample request object could look like this:
{
"jsonrpc": "2.0",
"method": "addPerson",
"params": {"firstName": "Ben", "lastName": "Langhinrichs"},
"id": 1
}
"jsonrpc": "2.0",
"method": "addPerson",
"params": {"firstName": "Ben", "lastName": "Langhinrichs"},
"id": 1
}
or like this
{
"jsonrpc": "2.0",
"method": "addPerson",
"params": ["Ben", "Langhinrichs"],
"id": 1
}
"jsonrpc": "2.0",
"method": "addPerson",
"params": ["Ben", "Langhinrichs"],
"id": 1
}
In all requests, the jsonrpc item is required and must be exactly "2.0". The method item is also required, and should be a valid method recognized by the server API. The params item, whether an object with named parameters or a positional array of parameters, is required only if the method requires parameters. The id item is required of a return value is defined and wanted. If there is no id item, there will be no response object unless the JSON could not be parsed. In this case, the Person is assigned an employee identifier which is returned, so the response object would be:
{
"jsonrpc": "2.0",
"result": "BL345A",
"id": 1
}
"jsonrpc": "2.0",
"result": "BL345A",
"id": 1
}
The response object will always have either a result or error, and will always include an id to tie it back to the request. An error might look like this if I spelled thee method name incorrectly
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Request method does not exist or is not available: addPreson"
},
"id": 1
}
In future posts, I'll show more real life examples so you can see how JSON-RPC works with batch requests, and ways in which the REST API differs from Domino Access Services.
Copyright © 2020 Genii Software Ltd.
What has been said: