Qu'est-ce que JSON-RPC ? Protocole, exemples, comparaison avec REST

Qu'est-ce que JSON-RPC ?

JSON-RPC est un protocole léger d'appel de procédure distante (RPC) qui encode requêtes et réponses en JSON. Le client indique une méthode et ses paramètres, le serveur l'exécute et renvoie un résultat ou une erreur. Il est sans état et indépendant du transport : la spécification JSON-RPC 2.0 (datée de 2010) décrit les messages, pas leur acheminement.

On le retrouve dans les nœuds Ethereum, dans le Language Server Protocol derrière les éditeurs de code et dans le Model Context Protocol des outils d'IA. Les trois utilisent des messages JSON-RPC 2.0.

Comment fonctionne un appel JSON-RPC

Une requête comporte quatre membres : jsonrpc (toujours "2.0"), method (le nom à appeler), params (facultatif, un tableau pour des arguments positionnels ou un objet pour des arguments nommés) et id (une chaîne ou un nombre de votre choix, renvoyé dans la réponse).

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

Une réponse réussie reprend le même id et contient un result :

{"jsonrpc": "2.0", "result": 19, "id": 1}

Un appel en échec contient un objet error avec un code numérique et un message à la place du résultat :

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}

Sur HTTP, c'est un unique POST vers une URL fixe, avec le nom de la méthode dans le corps et non dans le chemin. Vous pouvez l'essayer avec curl : envoyez l'objet de requête comme corps avec Content-Type: application/json.

Notifications et requêtes par lot

Une requête sans id est une notification : le serveur ne doit pas répondre, le client ne sait donc jamais si l'appel a abouti.

{"jsonrpc": "2.0", "method": "log", "params": {"level": "info"}}

Pour envoyer plusieurs appels d'un coup, placez les objets de requête dans un tableau. Le serveur répond par un tableau de réponses, dans un ordre quelconque d'après la spécification : associez donc chaque réponse à sa requête grâce à l'id.

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2, 4], "id": 1},
  {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 2}
]

Codes d'erreur standard

JSON-RPC, REST et gRPC en comparaison

Choisissez REST quand votre API repose sur des ressources et que vous voulez profiter du cache et des codes de statut HTTP. Choisissez JSON-RPC quand le modèle naturel est « exécute cette action », par exemple envoyer une transaction ou demander des complétions à un serveur de langage.

Erreurs courantes

• Considérer un HTTP 200 comme un succès. De nombreux serveurs renvoient 200 même quand le corps contient une error. Vérifiez le corps.
• Réutiliser un id au sein d'une connexion. Impossible d'associer les réponses, ce qui gêne surtout avec les lots.
• Supposer que les réponses d'un lot arrivent dans l'ordre. La spécification ne le garantit pas.
• Envoyer en notification un appel dont on attend la réponse. Sans id, vous ne verrez ni le résultat ni l'erreur.
• Utiliser null comme id. La spécification le déconseille et MCP l'interdit.
• Mettre des identifiants dans le contenu. Authentifiez-vous au niveau du transport, par exemple avec un bearer token dans l'en-tête Authorization.

Tester et superviser des endpoints JSON-RPC

Comme les erreurs reviennent souvent avec un statut 200, un simple contrôle du statut les rate. Vérifiez plutôt le corps : pas d'error, un result présent et un id identique. La supervision d'API LoadFocus prend en charge les assertions sur le code de statut, le corps et le temps de réponse, et les checks gratuits s'exécutent toutes les 5 minutes.

Pour les tests de charge, gardez en tête qu'un lot est une seule requête HTTP mais de nombreux appels de méthodes : il sollicite votre backend autrement que les mêmes appels envoyés un par un. Utilisez des ids uniques par appel et testez d'abord les méthodes qui touchent votre base de données ou un nœud blockchain. Les tests de charge LoadFocus exécutent des scripts JMeter et k6 capables d'envoyer des corps JSON, et ce guide sur le test de charge des API détaille la mise en place. L'entrée sur l'endpoint d'API explique ce que vous visez avec le test.

Questions fréquentes : JSON-RPC

JSON-RPC est-il toujours utilisé ?

Oui. Les clients Ethereum exposent une interface JSON-RPC, le Language Server Protocol l'utilise entre l'éditeur et le serveur de langage, et le Model Context Protocol s'appuie sur JSON-RPC 2.0. Il est moins courant pour les API web publiques, où REST domine.

JSON-RPC ou REST : lequel choisir ?

Aucun des deux en général. REST convient aux API publiques orientées ressources. JSON-RPC convient aux interfaces orientées actions où l'on appelle une méthode, et fonctionne sur d'autres transports que HTTP.

JSON-RPC utilise-t-il les codes de statut HTTP ?

La spécification n'en définit aucun. Les erreurs figurent dans le corps de la réponse et de nombreux serveurs renvoient 200 dans les deux cas. Certaines implémentations traduisent les erreurs en codes HTTP : consultez la documentation du serveur.

Comment authentifier une API JSON-RPC ?

Le protocole n'a pas d'authentification propre. Utilisez ce que le transport offre : une clé d'API ou un bearer token dans un en-tête sur HTTP, ou un mécanisme au niveau de la connexion avec WebSocket.

Quelle différence entre JSON-RPC 1.0 et 2.0 ?

La version 2.0 identifie les messages par le membre jsonrpc et marque une notification en omettant l'id (la 1.0 utilisait un id nul). Elle définit aussi les paramètres nommés, les requêtes par lot et une plage réservée de codes d'erreur. Les deux versions peuvent ne pas être compatibles : utilisez la 2.0 pour tout nouveau développement.

JSON-RPC peut-il pousser des données depuis le serveur ?

Sur une connexion persistante comme WebSocket, oui : chaque côté peut envoyer des notifications. Sur HTTP simple, seul le client initie une requête.