Als je een gemiddeld team vandaag de dag vraagt om een API te ontwerpen, dan zal vaak de uitkomst een REST-achtige API zijn. Ik zeg bewust REST-achtig omdat je vooral bij API’s die sterk georiënteerd zijn rondom acties en commando’s, vaak ziet dat de zuivere REST structuur niet echt gevolgd wordt. Voor uitwisseling tussen services onderling zul je dan mogelijk gebruik maken van gRPC, maar als je ook verwacht dat er javascript clients zijn dan is JSON-RPC zeker een standaard om ook eens te onderzoeken.

Wat is JSON_RPC

JSON-RPC werd begin jaren 2000 ontworpen als eenvoudig alternatief voor XML-RPC. Het doel was om een lichtgewicht specificatie op te zetten. Een minimalistisch protocol dat goed past bij webapplicaties en Javascript. De specificatie kun je terugvinden op https://www.jsonrpc.org/specification.

JSON-RPC is een request-response protocol. De communicatie kan in een klassieke client-server configuratie opgezet worden, maar ook bi-directioneel via bijvoorbeeld websockets.

In zijn meest versimpelde vorm ziet een JSON-RPC request en response eruit zoals hierboven. Je geeft aan welke versie van het protocol gebruikt wordt. Vervolgens geef je de naam van de methode aan die je wilt aanroepen. Daarna de parameters die voor deze methode geïmplementeerd zijn. Als laatste geef je een identificatie aan je request. Dit laatste is nodig omdat je in een request meerdere opdrachten kunt meegeven. In het resultaat wat terugkomt kun je dan eenvoudig zien welk resultaat bij welke opdracht hoort.

De response bevat vervolgens het resultaat van de request. Dit resultaat kan in feite elke willekeurig format zijn. In het voorbeeld hierboven is het een lijst met order informatie.

JSON-RPC werkt niet, zoals REST, met verschillende HTTP-verbs zoals GET, POST of PUT. Alle communicatie in dit protocol loopt over een POST wanneer je HTTP gebruikt, maar zoals al gezegd, omdat het protocol los staat van de transportlaag zou je ook via websockets, named pipes of TCP kunnen communiceren.

Wanneer gebruik je JSON-RPC

Deze manier van werken leent zich vooral goed voor services die veel command- en query-calls uitvoeren. Met andere woorden: als je domein vooral functioneel georiënteerd is (bijv. calculatePrice, approveOrder, validateInput), sluit JSON-RPC beter aan dan resource gebaseerde REST endpoints. In een artikel van de KU Leuven wordt mooi uitgelegd hoe REST vooral draait om resources en niet actie-gebaseerd is. Dat is meteen het grootste verschil, want in JSON-RPC is alles gerelateerd aan methodes die je op de server of client wilt aanroepen (niet geheel onverwacht gezien de naam Remote Procedure Call). De mogelijkheid om eenvoudig opdrachten te bundelen, en de mogelijkheid om ook bi-directionele communicatie op te zetten zijn ook twee mooie pluspunten.‑RPC beter aan dan resource‑gebaseerde REST

Hoe zet je een JSON-RPC service op

Microsoft heeft zelf een standaard package om JSON-RPC te implementeren: StreamJsonRpc. Er staan meteen ook linkjes in naar gerelateerde libraries om bijvoorbeeld een Javascript client op te zetten.

Een eenvoudige manier om methodes geschikt te maken voor JSON-RPC is het toevoegen van een JsonRpcMethod attribute:

In een minimale API maak je vervolgens een endpoint aan die je bij het opstarten registreert :

In het voorbeeld hierboven lopen alle services over één endpoint, maar je zou ook aparte endpoints per service kunnen introduceren.

Wil je een bi-directionele verbinding? Dan voeg je endpoints via websockets toe:

Hoe werkt beveiliging en progress in JSON-RPC

Qua authenticatie volgt JSON-RPC de standaard implementaties om gebruik te maken van bearer tokens. Let wel op dat je zelf regels implementeert voor rate-limiting. Implementeer ook gedegen monitoring via bijvoorbeeld OpenTelemetry. Als je javascript clients ondersteund is het belangrijk om specifieke functionaliteit voor deze applicaties toe te voegen. Denk aan CORS en CSRF beveiliging.

JSON‑RPC zelf definieert geen standaard cancel‑mechanisme. StreamJsonRpc ondersteunt cancellation via out‑of‑band tokens/messages tussen StreamJsonRpc peers. Met een “handmatige” JS‑client kun je een custom cancel‑methode afspreken, bv. rpc.cancel({ id }), die je server dan koppelt aan CancellationTokenSource.Cancel().

StreamJsonRpc kan progress‑events sturen; als je een JS‑client bouwt zonder StreamJsonRpc, behandel die als server‑initiated notifications (bijv. method: “$/progress”, params: { id, value }) en koppel ze in je #dispatch.

Voorbeeld:

Het verbinden van een client

Omdat JSON-RPC een standaard protocol is, is het eenvoudig om in verschillende talen een client te implementeren. Het onderstaande voorbeeld is een vereenvoudigde weergave van een client in javascript:

Nog wat praktische tips

  • Versiebeheer: encodeer de versie in de methodnaam (order.get/v2) of gebruik een prefix/namespace.
  • Retry/back‑off: implementeer een eenvoudige retry voor fetch (HTTP 5xx, netwerkfouten). Voor WebSockets: exponentiële reconnect.
  • Observability: log method, id, duur, payload size. Laat server een requestId teruggeven voor correlatie.
  • Beveiliging:
    • Bearer token in header.
    • WebSocket: standaard geen custom headers; gebruik querystring token, cookie of Subprotocols (als je server dat accepteert). Zorg voor TLS en valideer tokens server‑

Hoe documenteer je JSON-RPC API’s

Om je JSON-RPC API’s te documenteren gebruik je OpenRPC. Dit is een gestandaardiseerde machine-leesbare specificatie voor JSON-RPC. Vergelijkbaar met wat OpenAPI/Swagger is voor REST. Helaas is er voor OpenRPC geen standaard plugin voor .NET zoals bijvoorbeeld Swashbuckle voor OpenAPI

Conclusie

JSON‑RPC is een elegant, minimalistisch protocol dat minder populair, maar zeker wel relevant is. Het blinkt uit in eenvoud, performance en een duidelijke operationele structuur. Voor systemen met veel method calls, realtime communicatie of limited bandwidth kan JSON‑RPC een uitstekende keuze zijn. Hoewel REST geschikter blijft voor publieke API’s en resource‑gebaseerde domeinen, biedt JSON‑RPC juist daar voordelen waar eenvoud, snelheid en voorspelbaar gedrag centraal staan.