Transactions and JSON-RPC

2018-03-02 - Future - Tony Finch

The /update API endpoint that I outlined turns out to be basically JSON-RPC 2.0, so it seems to be worth making the new IP Register API follow that spec exactly.

However, there are a couple of difficulties wrt transactions.

The current not-an-API list_ops page runs each requested action in a separate transaction. It should be possible to make similar multi-transation batch requests with the new API, but my previous API outline did not support this.

A JSON-RPC batch request is a JSON array of request objects, i.e. the same syntax as I previously described for /update transactions, except that JSON-RPC batches are not transactional. This is good for preserving list_ops functionality but it loses one of the key points of the new API.

There is a simple way to fix this problem, based on a fairly well-known idea. XML-RPC doesn't have batch requests like JSON-RPC, but they were retro-fitted by defining a system.multicall method which takes an array of requests and returns an array of responses.

We can define transactional JSON-RPC requests in the same style, like this:

    { "jsonrpc": "2.0",
      "id": 0,
      "method": "transaction",
      "params": [ {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "foo",
          "params": { ... }
        }, {
          "jsonrpc": "2.0",
          "id": 2,
          "method": "bar",
          "params": { ... }
        } ]
    }

If the transaction succeeds, the outer response contains a "result" array of successful response objects, exactly one for each member of the request params array, in any order.

If the transaction fails, the outer response contains an "error" object, which has "code" and "message" members indicating a transaction failure, and an "error" member which is an array of response objects. This will contain at least one failure response; it may contain success responses (for actions which were rolled back); some responses may be missing.

Edited to add: I've described some more refinements to this idea