JSON+RPC 1.0 Specification
Date: 2024-08-06
Author: Mike Dotty <dottedmag@dottedmag.net>
Table of Contents
1 Overview
JSON+RPC is a programming interface style.
2 Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are not used in this document, as the author finds RFC 2119 a bit dubious: it is not clear WHO is required to do WHAT, on WHOSE AUTHORITY, and WHAT THE CONSEQUENCES ARE if the requirements are not fulfilled.
3 Compatibility
The JSON+RPC specification is expected to perpetually stay at version 1.0, so there are no compatibility considerations.
4 Protocol
Expose functionality using RPC (requests and responses), and use JSON as a serialization format: you then have a JSON+RPC interface.
5 Examples
Almost every API in the last 20 years that isn't strictly REST/HATEOAS.
6 License
The JSON+RPC 1.0 specification is distributed under CC0 1.0.
JSON+RPC vs. JSON-RPC
JSON-RPC prescribes a specific protocol: it introduces methods, method names, parameters (positional or named, but not both), correlation identifiers, error values and their taxonomy, and request batching.
JSON+RPC acknowledges that, on the one hand, JSON-RPC is too straight-jacketed and that makes it hard to express some interfaces (streaming responses? unsolicited tack-in-to-other-response events?), and, on the other hand, is too handwavy and does not help to automatically produce valuable code from the interface description, so JSON+RPC does away with all of it.
JSON+RPC is a convenient name to put onto your interface description, instead of saying, "This interface is in RPC style and uses JSON as a serialization format". It lets a designer create whatever interface is needed for the task at hand.
What is JSON? What is RPC?
Seriously?
What is DVD?
A chandelier ornament in the form of a shiny disc that previously was used to carry data around.
HP developed a writable DVD disc and named it DVD+R. Pioneer developed a writable DVD disc and named it DVD-R. We, customers, groaned.
What uses JSON+RPC?
All software that uses JSON-RPC has been unwittingly using JSON+RPC, so it's got a pretty broad user base for a protocol that's less than few years old!
Moreover, all the other software whose designers looked at JSON-RPC and decided to roll their own RPC using JSON as a serialization format also uses JSON+RPC.
GraphQL too.
Is this a joke?
Not really. It is useful to have a name for a fairly common interface style on the Web: RPC with JSON as a serialization format.
JSON-RPC is already taken by a specific realization of this interface style, whose name alone and the presence of a specification probably explain the (admittedly modest) popularity it enjoys.
JSON+RPC is definitely a tongue-in-cheek name and a play on JSON-RPC. Hopefully, enough engineers remember the DVD-R/DVD+R era, so the name won't be too confusing early on. If/when it becomes entrenched, it won't matter that nobody remembers DVDs anymore.