GFI KerioConnect® – Spécification JSON-RPC 2.0

Présentation générale

JSON-RPC est un protocole d'appel de procédure à distance (RPC) léger et sans état. Cette spécification définit principalement plusieurs structures de données ainsi que les règles relatives à leur traitement. Elle est indépendante du protocole de transport, dans la mesure où ses concepts peuvent être utilisés au sein d'un même processus, via des sockets, via HTTP ou dans divers environnements de passage de messages. Elle utilise JSON (RFC 4627) comme format de données.

C'est conçu pour être simple !

Conventions

Les termes clés « MUST », « MUST NOT », « REQUIRED », « SHALL », « SHALL NOT », « SHOULD », « SHOULD NOT », « RECOMMENDED », « MAY » et « OPTIONAL » figurant dans le présent document doivent être interprétés conformément à la RFC 2119.

Comme JSON-RPC utilise JSON, il dispose du même système de types (voir http://www.json.org ou la RFC 4627). JSON peut représenter quatre types primitifs (chaînes de caractères, nombres, booléens et null) et deux types structurés (objets et tableaux). Dans la présente spécification, le terme « primitif » désigne l’un quelconque de ces quatre types primitifs JSON. Le terme « structuré » désigne l’un ou l’autre des types structurés JSON. Dans le présent document, chaque fois qu’il est fait référence à un type JSON, la première lettre est toujours en majuscule : Objet, Tableau, Chaîne, Nombre, Booléen, Null. Les termes « True » et « False » s’écrivent également en majuscules.

Tous les noms de membres échangés entre le client et le serveur et pris en compte pour toute forme de mise en correspondance doivent être considérés comme sensibles à la casse. Les termes « fonction », « méthode » et « procédure » peuvent être considérés comme interchangeables.

Le client est défini comme la source des objets « Request » et le gestionnaire des objets « Response ».
Le serveur est défini comme la source des objets « Response » et le gestionnaire des objets « Request ».

Une implémentation de cette spécification pourrait facilement remplir ces deux rôles, voire simultanément, pour différents clients ou pour un même client. Cette spécification n'aborde pas ce niveau de complexité.

Compatibilité

Les objets « Request » et « Response » de JSON-RPC 2.0 peuvent ne pas fonctionner avec les clients ou serveurs JSON-RPC 1.0 existants. Cependant, il est facile de distinguer les deux versions, car la version 2.0 comporte toujours un membre nommé « jsonrpc » dont la valeur de type chaîne de caractères est « 2.0 », contrairement à la version 1.0. La plupart des implémentations 2.0 devraient envisager de prendre en charge les objets 1.0, même si ce n’est pas le cas pour les aspects « peer-to-peer » et « class hinting » de la version 1.0.

Objet de requête

Un appel RPC consiste à envoyer un objet Request à un serveur. L'objet Request comporte les membres suivants :

jsonrpc – Chaîne de caractères indiquant la version du protocole JSON-RPC. DOIT être exactement « 2.0 ».

méthode – Une chaîne de caractères contenant le nom de la méthode à invoquer. Les noms de méthodes commençant par le mot « rpc » suivi d’un point (U+002E ou ASCII 46) sont réservés aux méthodes et extensions internes à RPC et NE DOIVENT PAS être utilisés à d’autres fins.

params – Une valeur structurée contenant les valeurs des paramètres à utiliser lors de l'appel de la méthode. Cet élément PEUT être omis.

id - Identifiant défini par le client qui DOIT contenir une chaîne de caractères, un nombre ou la valeur NULL s'il est présent. S'il n'est pas présent, on considère qu'il s'agit d'une notification. La valeur NE DEVRAIT normalement pas être nulle [1] et les nombres NE DEVRAIENT PAS comporter de décimales [2]

Le serveur DOIT renvoyer la même valeur dans l'objet Response s'il est présent. Cet élément sert à établir une corrélation entre le contexte des deux objets.

[1] L'utilisation de la valeur « Null » pour le membre « id » d'un objet Request est déconseillée, car la présente spécification utilise la valeur « Null » pour les réponses dont l'identifiant est inconnu. De plus, comme JSON-RPC 1.0 utilise la valeur « Null » pour l'identifiant des notifications, cela pourrait prêter à confusion lors du traitement.

[2] Les fractions peuvent poser problème, car de nombreuses fractions décimales ne peuvent pas être représentées exactement sous forme de fractions binaires.

Notification

Une notification est un objet Request dépourvu de membre « id ». Un objet Request qui est une notification indique que le client n'est pas intéressé par l'objet Response correspondant ; par conséquent, aucun objet Response ne doit être renvoyé au client. Le serveur NE DOIT PAS répondre à une notification, y compris celles qui font partie d'une requête groupée.

Par définition, les notifications ne peuvent pas faire l'objet d'une confirmation, puisqu'elles ne comportent pas d'objet « Response » à renvoyer. De ce fait, le client ne serait pas informé d'éventuelles erreurs (telles que, par exemple, « Paramètres non valides. » ou « Erreur interne. »).

Structures de paramètres

S'ils existent, les paramètres de l'appel RPC DOIVENT être fournis sous forme de valeur structurée, soit par position via un tableau, soit par nom via un objet.

• par position : les paramètres DOIVENT être un tableau contenant les valeurs dans l'ordre attendu par le serveur.
• par nom : les paramètres DOIVENT être un objet dont les noms de membres correspondent aux noms des paramètres attendus par le serveur. L'absence des noms attendus PEUT entraîner l'apparition d'une erreur. Les noms DOIVENT correspondre exactement, y compris en majuscules et minuscules, aux paramètres attendus par la méthode.

Objet de réponse

Lorsqu'un appel RPC est effectué, le serveur DOIT répondre par une réponse, sauf dans le cas des notifications. La réponse se présente sous la forme d'un objet JSON unique, comportant les éléments suivants :

jsonrpc – Chaîne de caractères indiquant la version du protocole JSON-RPC. DOIT être exactement « 2.0 ».

résultat – Cet élément est OBLIGATOIRE en cas de réussite.
Cet élément NE DOIT PAS exister si une erreur s'est produite lors de l'appel de la méthode.
La valeur de cet élément est déterminée par la méthode appelée sur le serveur.

erreur – Cet élément est OBLIGATOIRE en cas d'erreur.
Cet élément NE DOIT PAS exister si aucune erreur n'a été déclenchée lors de l'appel.
La valeur de cet élément DOIT être un objet.

id – Ce membre est OBLIGATOIRE.
Il DOIT correspondre à la valeur du membre « id » de l’objet Request.
En cas d’erreur lors de la détection de l’identifiant dans l’objet Request (par exemple, erreur d’analyse ou requête non valide), il DOIT être nul.

Il FAUT inclure soit le membre « result », soit le membre « error », mais il NE FAUT PAS inclure les deux.

Objet d'erreur

Lorsqu'un appel RPC rencontre une erreur, l'objet Response DOIT contenir le membre « error » dont la valeur est un objet comportant les membres suivants :

code – Un nombre indiquant le type d'erreur qui s'est produite.
Il DOIT s'agir d'un nombre entier.

message – Une chaîne de caractères fournissant une brève description de l'erreur.
Le message DEVRAIT se limiter à une seule phrase concise.

data – Valeur primitive ou structurée contenant des informations supplémentaires sur l'erreur.
Ce paramètre peut être omis.
La valeur de cet élément est définie par le serveur (par exemple, informations détaillées sur l'erreur, erreurs imbriquées, etc.).

Les codes d'erreur compris entre -32768 et -32000 inclus sont réservés à des erreurs prédéfinies. Tout code compris dans cette plage, mais non défini explicitement ci-dessous, est réservé à un usage futur. Ces codes d'erreur sont pratiquement identiques à ceux proposés pour XML-RPC à l'adresse suivante : http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Le reste de l'espace est réservé aux erreurs définies par l'application.

Lot

Pour envoyer plusieurs objets « Request » simultanément, le client PEUT envoyer un tableau contenant ces objets « Request ».

Le serveur doit répondre avec un tableau contenant les objets `Response` correspondants, une fois que tous les objets `Request` du lot ont été traités. Il DOIT exister un objet `Response` pour chaque objet `Request`, sauf qu’il NE DOIT PAS y avoir d’objets `Response` pour les notifications. Le serveur PEUT traiter un appel RPC par lots comme un ensemble de tâches simultanées, en les traitant dans n’importe quel ordre et avec n’importe quel degré de parallélisme.

Les objets « Response » renvoyés par un appel par lots PEUVENT être renvoyés dans n'importe quel ordre au sein du tableau. Le client DEVRAIT établir une correspondance entre les contextes de l'ensemble des objets « Request » et de l'ensemble résultant d'objets « Response » en se basant sur le membre « id » de chaque objet.

Si l'appel RPC par lots lui-même n'est pas reconnu comme un JSON valide ou comme un tableau contenant au moins une valeur, la réponse du serveur DOIT être un objet Response unique. Si le tableau Response, tel qu'il doit être envoyé au client, ne contient aucun objet Response, le serveur NE DOIT PAS renvoyer un tableau vide et ne doit rien renvoyer du tout.

Exemples

Syntaxe :

--> data sent to Server
<-- data sent to Client

Appel RPC avec des paramètres positionnels :

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}
--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

Appel RPC avec des paramètres nommés :

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

Une notification :

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

Appel RPC d'une méthode inexistante :

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": "1"}

Appel RPC avec un JSON non valide :

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}

Appel RPC avec un objet Request non valide :

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}

Appel RPC « Batch », JSON non valide :

--> [ {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},{"jsonrpc": "2.0", "method" ]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}

Appel RPC avec un tableau vide :

--> [] 
<-- "jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}

Appel RPC avec un lot non valide (mais non vide) :

--> [1]
<-- [ {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} ]

Appel RPC avec un lot non valide :

--> [1,2,3]
<-- [
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}, 
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}, 
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} 
]

Appel RPC par lots :

--> [
 {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
 {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
 {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
 {"foo": "boo"},
 {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
 {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
]
<-- [
 {"jsonrpc": "2.0", "result": 7, "id": "1"},
 {"jsonrpc": "2.0", "result": 19, "id": "2"},
 {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
 {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found."}, "id": "5"},
 {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
]

Appel RPC « Batch » (toutes les notifications) :

--> [
 {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
 {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
]
<-- //Nothing is returned for all notification batches

Extensions

Les noms de méthodes commençant par « rpc. » sont réservés aux extensions système et NE DOIVENT PAS être utilisés à d'autres fins. Chaque extension système est définie dans une spécification correspondante. Toutes les extensions système sont FACULTATIVES.

Copyright (C) 2007-2010 par le groupe de travail JSON-RPC

Le présent document et ses traductions peuvent être utilisés pour mettre en œuvre JSON-RPC ; ils peuvent être copiés et communiqués à des tiers ; et des œuvres dérivées visant à les commenter, à les expliquer ou à faciliter leur mise en œuvre peuvent être élaborées, copiées, publiées et diffusées, en tout ou en partie, sans aucune restriction, à condition que la mention de droits d'auteur ci-dessus et le présent paragraphe figurent sur toutes ces copies et œuvres dérivées. Toutefois, le présent document lui-même ne peut en aucun cas être modifié.

Les autorisations limitées accordées ci-dessus sont perpétuelles et ne seront pas révoquées.

Le présent document et les informations qu’il contient sont fournis « EN L’ÉTAT » et TOUTES LES GARANTIES, EXPRESSES OU IMPLICITES, SONT EXCLUES, Y COMPRIS, SANS S’Y LIMITER, TOUTE GARANTIE SELON LAQUELLE L’UTILISATION DES INFORMATIONS CONTENUES DANS LE PRÉSENT DOCUMENT NE PORTERA PAS ATTEINTE À DES DROITS QUELCONQUES, OU TOUTE GARANTIE IMPLICITE DE QUALITÉ MARCHANDE OU D’ADÉQUATION À UN USAGE PARTICULIER.