JSON-RPC - JSON-RPC

JSON-RPC est un protocole d' appel de procédure à distance codé en JSON . Il est similaire au protocole XML-RPC , ne définissant que quelques types de données et commandes. JSON-RPC permet d'envoyer des notifications (données envoyées au serveur qui ne nécessitent pas de réponse) et d'envoyer plusieurs appels au serveur qui peuvent recevoir une réponse asynchrone.

Histoire

Version La description Daté
1,0 Version originale 2005
1.1 DEO Ébauche de travail . Ajoute des paramètres nommés, ajoute des codes d'erreur spécifiques et ajoute des fonctions d'introspection. 2006-08-07
1.1 Alt Suggestion pour un simple JSON-RPC 1.1 . Proposition alternative à 1.1 WD. 2007-05-06
1.1 Spécification de l'objet Spécification de l'objet . Proposition alternative à 1.1 WD/1.1ALT. 2007-07-30
1.2 Proposition . Une révision ultérieure de ce document a été renommée en 2.0. 2007-12-27
2.0 Proposition de cahier des charges 2009-05-24
2.0 (Révisé-) spécification 2010-03-26

Usage

JSON-RPC fonctionne en envoyant une requête à un serveur implémentant ce protocole. Le client dans ce cas est généralement un logiciel ayant l'intention d'appeler une méthode unique d'un système distant. Plusieurs paramètres d'entrée peuvent être transmis à la méthode distante sous forme de tableau ou d'objet, tandis que la méthode elle-même peut également renvoyer plusieurs données de sortie. (Cela dépend de la version implémentée.)

Tous les types de transfert sont des objets uniques, sérialisés à l'aide de JSON. Une requête est un appel à une méthode spécifique fournie par un système distant. Il peut contenir trois membres :

  • method- Une chaîne avec le nom de la méthode à appeler. Noms de méthode commençant par "rpc". sont réservés aux méthodes internes à rpc.
  • params- Un objet ou un tableau de valeurs à transmettre en paramètres à la méthode définie. Ce membre peut être omis.
  • id- Une chaîne ou un nombre non fractionnaire utilisé pour faire correspondre la réponse à la demande à laquelle elle répond. Ce membre peut être omis si aucune réponse ne doit être renvoyée.

Le destinataire de la demande doit répondre avec une réponse valide à toutes les demandes reçues. Une réponse peut contenir les membres mentionnés ci-dessous.

  • result- Les données renvoyées par la méthode invoquée. Cet élément est formaté en tant qu'objet JSON-stat. Si une erreur s'est produite lors de l'appel de la méthode, ce membre ne doit pas exister.
  • error- Un objet error s'il y a eu une erreur lors de l'appel de la méthode, sinon ce membre ne doit pas exister. L'objet doit contenir le code des membres (entier) et le message (chaîne). Un membre de données facultatif peut contenir d'autres données spécifiques au serveur. Il existe des codes d'erreur prédéfinis qui suivent ceux définis pour XML-RPC.
  • id - L'identifiant de la requête à laquelle il répond.

Comme il existe des situations où aucune réponse n'est nécessaire ou même souhaitée, des notifications ont été introduites. Une notification est similaire à une demande à l'exception de l'identifiant, qui n'est pas nécessaire car aucune réponse ne sera renvoyée. Dans ce cas, la idpropriété doit être omise (version 2.0) ou être null(version 1.0).

Exemples

Dans ces exemples, -->désigne les données envoyées à un service ( request ), tandis que <--désigne les données provenant d'un service. Bien qu'elle <--soit souvent appelée une réponse dans l'informatique client-serveur, selon la version JSON-RPC, elle n'implique pas nécessairement une réponse à une requête .

Version 2.0

Demande et réponse : 

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

Notification (pas de réponse) : 

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

Version 1.1 (Brouillon de travail)

Demande et réponse : 

--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}

Version 1.0

Demande et réponse : 

--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

Voir également

Les références

  1. ^ "spécification - JSON-RPC - Trac" . Archivé de l'original le 2008-05-17 . Récupéré le 14-05-2008 .
  2. ^ "Spécification JSON-RPC 2.0" . id : un identifiant établi par le client qui DOIT contenir une chaîne, un nombre ou une valeur NULL s'il est inclus. S'il n'est pas inclus, il s'agit d'une notification. La valeur NE DEVRAIT normalement pas être nulle et les nombres NE DEVRAIENT PAS contenir de parties fractionnaires
  3. ^ "Spécification JSON-RPC 2.0" . Une notification est un objet Request sans membre "id". Un objet Request qui est une Notification signifie le manque d'intérêt du Client pour l'objet Response correspondant, et en tant que tel, aucun objet Response n'a besoin d'être retourné au client. Le serveur NE DOIT PAS répondre à une notification, y compris à celles qui font partie d'une demande par lots. Les notifications ne sont pas confirmables par définition, car elles n'ont pas d'objet Response à renvoyer. En tant que tel, le Client n'aurait connaissance d'aucune erreur (comme par exemple "Params invalides", "Erreur interne").
  4. ^ "Spécification JSON-RPC 2.0" . résultat : Ce membre est OBLIGATOIRE en cas de réussite. Ce membre NE DOIT PAS exister s'il y a eu une erreur lors de l'appel de la méthode. La valeur de ce membre est déterminée par la méthode invoquée sur le serveur.
  5. ^ "Spécification JSON-RPC 2.0" . error: Ce membre est OBLIGATOIRE en cas d'erreur. Ce membre NE DOIT PAS exister s'il n'y a pas eu d'erreur déclenchée pendant l'invocation. La valeur de ce membre DOIT être un objet tel que défini au paragraphe 5.1.
  6. ^ "Spécification JSON-RPC 2.0" . Objet d'erreur : lorsqu'un appel rpc rencontre une erreur, l'objet de réponse DOIT contenir le membre d'erreur avec une valeur qui est un objet avec les membres suivants : (code) - Un nombre qui indique le type d'erreur qui s'est produit. Cela DOIT être un entier. (message) - Une chaîne fournissant une brève description de l'erreur. Le message DEVRAIT être limité à une seule phrase concise. (données) - Une valeur primitive ou structurée qui contient des informations supplémentaires sur l'erreur. Cela peut être omis. La valeur de ce membre est définie par le serveur (par exemple, informations détaillées sur les erreurs, erreurs imbriquées, etc.).

Liens externes