Ben Langhinrichs

Photograph of Ben Langhinrichs

E-mail address - Ben Langhinrichs







Recent posts

Mon 26 Oct 2020

Data from Domino 1: Rows ≠ Documents



Wed 7 Oct 2020

Custom Domino Extensions in a Modern AppDev World



Tue 22 Sep 2020

Exciton Boost - Barbarians are at the gate


November, 2020
SMTWTFS
01 02 03 04 05 06 07
08 09 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30

Search the weblog





























Genii Weblog

Quick primer on JSON-RPC

Fri 14 Aug 2020, 12:20 PM



by Ben Langhinrichs
 
Inline JPEG image
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
}
 
or like this
 
{
  "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
}
 
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:

No documents found

Have your say:

Name *:
E-mail:
e-mail addresses will not be displayed on this site
Comment *:


<HTML is not allowed>
Linking: Add links as {{http://xxx|title}}, and they will be activated once approved
Blocked? Unable to post a comment? Please read this for a possible explanation...