Mardi, 15 Juin 1999, by Dave Winer. Traduction : Jean-Christophe Charvy.
Version originale : http://www.xml-rpc.com/spec
Cette spécification documente le protocole XML-RPC implémenté dans UserLand Frontier 5.1.
Pour une explication non-technique, se référer à XML-RPC for Newbies.
Cette page fournit toute l'information dont un développeur a besoin.
Généralités
XML-RPC est un protocole d'Appel de Procédure à Distance (Remote Procedure Calling) qui fonctionne sur Internet.
Un message XML-RPC est une requête HTTP POST. Le corps de la requête est en XML. Une procédure s'exécute sur le serveur, et la valeur qu'elle retourne est également formatée en XML.
Les paramètres d'une procédure peuvent être des scalaires, des numériques, des chaînes de caractères, des dates, ... etc. Ils peuvent également des structures complexes de listes et d'enregistrements.
Exemple de requête
Voici un exemple de requête XML-RPC :
POST /RPC2 HTTP/1.0 User-Agent: Frontier/5.1.2 (WinNT) Host: betty.userland.com Content-Type: text/xml Content-length: 181<?xml version="1.0"?> <methodCall> <methodName>examples.getStateName</methodName> <params> <param> <value><i4>41</i4></value> </param> </params> </methodCall>
Caractéristiques de l'entête HTTP
Le format de l'URI sur la première ligne de l'entête n'est pas spécifié. Par exemple, il peut être omis, ou ce peut être un unique slash, si le serveur reçoit uniquement des appels XML-RPC. Cependant, si le serveur prend en charge diverses requêtes HTTP qui arrivent, il est permis que l'URI aide à diriger la requête vers le code qui traite les requêtes XML-RPC. (Dans l'exemple, l'URI est /RPC2, indiquant au serveur de diriger la requête vers le service "RPC2".)
Le client (User-Agent) et l'hôte (Host) doivent être spécifiés.
Le type de contenu (Content-Type) est text/xml.
La taille du contenu (Content-Length) doit être spécifiée et doit être exacte.
Format du corps du message
Le corps de la requête est en XML, il s'agit d'une unique structure <methodCall>.
La structure <methodCall> doit contenir un sous-élément <methodName>, il s'agit d'une chaîne de caractère, qui contient le nom de la méthode qui doit être appelée. La chaîne de caractère ne peut contenir que des caractères non-symboliques : des lettres de A à Z, en majuscules ou en minucules, des chiffres de 0 à 9, l'espace souligné (underscore), le point, les deux points et le slash. Il revient intégralement au serveur de décider comment interpréter les caractères dans une clause methodName.
Par exemple, la valeur de <methodName> peut être le nom d'un fichier contenant un script inoqué quand une requête arrive. Cela peut être le nom d'un champ dans une table d'une base de données. Ou bien cela peut être le chemin d'accès à un fichier à travers une arborescence de répertoires.
Si l'appel de la procédure comporte des paramètres, la structure <methodCall> doit contenir un sous-élément <params>. Le sous-élément <params> peut contenir n'importe quel nombre de sous-éléments <param>, chacun ayant une clause <value>.
Les clauses <value> peuvent être scalaires, le type est indiqué en insérant dans la valeur, une des balises listées ci-dessous :
| Tag | Type | Example |
| <i4> or <int> | entier (signé sur 4 octets) | -12 |
| <boolean> | 0 (faux, false) ou 1 (vrai, true) | 1 |
| <string> | chaine de caractères | bonjour à tous |
| <double> | nombre signé à virgule flottante, double précision | -12.214 |
| <dateTime.iso8601> | date / heure | 19980717T14:08:55 |
| <base64> | binaire base64 | eW91IGNhbid0IHJlYWQgdGhpcyE= |
Si aucun type n'est indiqué, le type est string.
Structures <struct>
Une valeur peut également être du type <struct>.
Une structure <struct> contient des sous-éléments <member> et chaque sous-élément <member> contient une clause <name> et une clause <value>.
Voici un exemple de structure <struct> à deux éléments :
<struct>
<member>
<name>lowerBound</name>
<value><i4>18</i4></value>
</member>
<member>
<name>upperBound</name>
<value><i4>139</i4></value>
</member>
</struct>
Les structures <struct> peuvent être récursives, n'importe quelle clause <value> peut contenir une structure <struct> ou n'importe quel autre type, y compris une structure <array>, décrite ci-dessous.
Structures <array>
Une valeur peut également être du type <array>.
Une structure <array> contient un unique élément <data>, qui peut contenir n'importe quel nombre de clauses <value>s.
Voici un exemple de structure <array> à quatre éléments :
<array>
<data>
<value><i4>12</i4></value>
<value><string>Egypt</string></value>
<value><boolean>0</boolean></value>
<value><i4>-31</i4></value>
</data>
</array>
Les éléments des clauses <array> n'ont pas de noms.
Vous pouvez mélanger les types comme le montre l'exemple ci-dessus.
Les structures <arrays> peuvent être récursives, n'importe quelle clause <value> peut contenir une structure <array> ou n'importe quel autre type, y compris une structure <struct>, décrite plus haut.
Un exemple de réponse
Voici un exemple de réponse à une requête XML-RPC :
HTTP/1.1 200 OK Connection: close Content-Length: 158 Content-Type: text/xml Date: Fri, 17 Jul 1998 19:55:08 GMT Server: UserLand Frontier/5.1.2-WinNT<?xml version="1.0"?> <methodResponse> <params> <param> <value><string>South Dakota</string></value> </param> </params> </methodResponse>
Format de réponse
Même si il y a une erreur de bas niveau, le retour est toujours 200 OK.
Le type de contenu (Content-Type) est text/xml. La taille du contenu (Content-Length) doit être spécifiée et doit être exacte.
> Le corps de la réponse est une simple struture XML, il s'agit d'une structure <methodResponse>, qui peut contenir une seule clause <params> qui contient une seule clause <param> qui contient une seule clause <value>.
La structure <methodResponse> peut également contenir une clause <fault> qui contient une clause <value> qui contient une structure <struct> comportant deux éléments, l'un nommé <faultCode> et qui est un entier (<int>) et l'autre nommé <faultString>, et qui est une chaîne de caractères (<string>).
Une structure <methodResponse> ne peut contenir à la fois une clause <fault> et une clause <params>.
Exemple de clause <fault>
HTTP/1.1 200 OK Connection: close Content-Length: 426 Content-Type: text/xml Date: Fri, 17 Jul 1998 19:55:02 GMT Server: UserLand Frontier/5.1.2-WinNT<?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value><int>4</int></value> </member> <member> <name>faultString</name> <value><string>Too many parameters.</string></value> </member> </struct> </value> </fault> </methodResponse>
Pare-feus/Firewalls. L'objectif de ce protocole est d'établir une base compatible à travers différents environnements, il n'y a aucun gain au-delà des possibilités de l'interface des CGI. Un pare-feu peut surveiller les requêtes POST dont le Content-Type est text/xml.
Facilité d'apprentissage. Nous avons souhaité un format clair et extensible qui serait extrêmement simple. Il doit être possible pour un développeur HTML d'être en mesure d'ouvrir un fichier qui contient l'appel à une procédure XML-RPC, et de comprendre ce que cela fait, d'être capable de le modifier et que cela fonctionne à la première ou à la deuxième tentative.
Facilité d'implémentation. Nous avons également voulu que ce soit un protocole facile à implémenter, qui pourrait rapidement être adapté pour fonctionner dans d'autres environnements ou sur d'autres systèmes d'exploitation.
Mise à jour du 21 janvier 1999
Les questions suivantes ont été posées sur le groupe de discussion UserLand alors que XML-RPC était implémenté en Python.
Non, vous ne pouvez pas l'enlever si la procédure s'est déroulée avec succès. Il n'y a que deux options, ou bien une réponse contient une structure <params>, ou bien elle contient une structure <fault>. C'est pourquoi nous avons utilisé le mot "peut" dans cette phrase.
Oui, boolean est un type de données spécifique. Certains langages/environnements permettent un conversion facile de zéro en faux (false) et de un en vrai (true), mais si vous voulez dire "vrai" (true), envoyez un type "boolean" avec la valeur "true", ainsi votre intention ne sera pas mal comprise.
Un entier est un nombre signé sur 32 bits. Vous pouvez inclure un signe plus ou moins au début de la chaîne de caractères numériques. Les zéros devant l'entier sont ignorés. Les espaces ne sont pas autorisés. Uniquement des caractères numériques précédés par un signe plus ou un signe moins.
Il n'y a aucune représentation pour l'infini (positif ou négatif) ou pour la clause "non numérique". A ce jour, seule la notation décimale est autorisée, un signe plus ou moins, suivi par un certain nombre de caractères numériques, suivi par un point ou une virgule, puis un certain nombre de caractères numériques. Les espaces ne sont pas autorisés. L'étendue des valeurs autorisées dépend de l'implémentation, et n'est pas spécifiée.
N'importe quel caractère est autorisé dans une "string" excepté < et &, qui sont encodés en < and &. Une "string" peut être utilisée pour encoder des données binaires.
L'élément "struct" ne conserve pas l'ordre des clés. Les deux structures sont équivalentes.
Une structure <fault> ne peut pas contenir des membres autres que ceux spécifiés. Ceci est vrai pour toutes les autres structures. Nous pensons que la spécification est assez flexible pour que tout besoin raisonnable de tansfert de données puisse être adapté dans les structures indiquées. Si vous pensez fermement que ceci n'est pas exact, merci de poster un message sur le groupe de discussion.
Il n'y a pas de liste globale de codes d'erreur. Il revient au développeur qui implémente le serveur ou à des normes de haut niveau, de spécifier les codes d'erreur.
Ne vous préoccupez pas de la zone horaire. Il devrait être spécifié par le serveur dans sa documentation quelle hypothèse il prend sur les zones horaires.
Suppléments
Suppression de "ASCII" de la définition de "string".
Changement des dates de copyright, ci-dessous, de 1999-2003 à 1998-99.
© Copyright 1998-2003 UserLand Software. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works.
This document may not be modified in any way, such as by removing the copyright notice or references to UserLand or other organizations. Further, while these copyright restrictions apply to the written XML-RPC specification, no claim of ownership is made by UserLand to the protocol it describes. Any party may, for commercial or non-commercial purposes, implement this protocol without royalty or license fee to UserLand. The limited permissions granted herein are perpetual and will not be revoked by UserLand or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and USERLAND DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.