JSON+RPC 1.0 Specification
Date: 2024-08-06
Author: Mike Dotty <jsonplusrpc@dt.mg>
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 the 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), use JSON as a serialization format. You have a JSON+RPC interface.
5 Examples
Basically every API invented in the last 20 years that is not 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": a designer is free to design 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 one year 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 use JSON+RPC.
GraphQL too.
Is this a joke?
Not really. It is useful to have a name for a quite 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 the name alone and the presence of a specification probably explains 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 DVD-R/DVD+R era, so the name won't be too confusing at the beginning. If/when it becomes entrenched, it won't matter that nobody remembers DVDs anymore.