Опубликована Dave Winer, 6/15/99 в 2:40:29 PM.
Эта спецификация документирует протокол XML-RPC осуществленный в UserLand Frontier 5.1.
Для нетехнического обьяснения, смотрите XML-RPC for Newbies.
Эта страница обеспечивает всю информацию в которой нуждается разработчик.
Обзор
XML-RPC это протокол вызова удаленных процедур работающий через Интернет.
Сообщение XML-RPC – это HTTP-POST запрос. Тело запроса построено на XML. Процедура выполняется на сервере и возвращаемое значение также форматируется в XML.
Параметры процедуры могут быть скалярными величинами, числами, строками, датами, и.т.д.; а также могут быть записями (records) и списочными структурами.
Пример запроса
Ниже приведен пример 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> </methodCal
Условия заголовка
Формат URI в первой строке заголовка не специфицируется. Например, он может быть пустой или содержать просто slash, если сервер только обрабатывает XML-RPC запросы. Однако, если сервер обрабатывает смесь входящих HTTP-запросов, мы позволяем URI помогать маршрутизировать запрос к коду который обрабатывает XML-RPC запрос. (В примере выше, URI – "/RPC2", это сообщает серверу направлять запрос к обработчику "RPC2".)
Поле User-Agent и Host должны быть заполнеными.
Поле ContentType – text/xml.
Поле Content-Length должно быть заполненым и содержать корректное значение.
Формат тела сообщения
Тело строится на XML, в простой структуре <methodCall>.
Элемент "<methodCall>" должен содержать дочерний элемент <methodName> – строку, содержащую имя вызываемого метода. Строка может содержать только символы идентификатора, символы верхнего и нижнего регистра от A до Z, цыфры 0-9, символ подчеркивания, точку, двоеточие и slash. Это полностью зависит от сервера решить как интерпретировать символы в methodName.
Например, methodName содержать имя файла содержащего скрипт, который выполняет данный входящий запрос. Это может быть имя строки в базе данных. Или это может быть путь к файлу содержащему иерархию папок и файлов.
Если вызов процедуры имеет параметры, то <methodCall> должен содержать под-элемент <params>. Дочерний элемент <params> может содержать любое количество <param>'ов, каждый из которых имеет значение – <value>.
"<value>" может быть скаляром. Тип определяется вложенностью значения в один из тегов перечисленных в этой таблице:
| Tag | Type | Example |
| <i4> or <int> | four-byte signed integer | -12 |
| <boolean> | 0 (false) или 1 (true) | 1 |
| <string> | ASCII строка | hello world |
| <double> | double-precision signed floating point number | -12.214 |
| <dateTime.iso8601> | дата/время | 19980717T14:08:55 |
| <base64> | base64-encoded binary | eW91IGNhbid0IHJlYWQgdGhpcyE= |
Эсли тип не показывается значит это строка.
<struct>
Значение также может иметь тип <struct>.
<struct> содержит єлементы <member>, а каждый <member> содержит <name> и <value>.
А вот пример двухелементной структуры <struct>:
<struct>
<member>
<name>lowerBound</name>
<value><i4>18</i4></value>
</member>
<member>
<name>upperBound</name>
<value><i4>139</i4></value>
</member>
</struct>
Структуры могут быть рекурсивными – любой <value>может содержать <struct> или любой другой тип, включая <array>, описанный ниже.
Массивы <array>
Тип значения может также быть <array>.
<array> содержит один элемент <data>, который может содержать любое количество <value>.
Вот пример четырехэлементного массива:
<array>
<data>
<value><i4>12</i4></value>
<value><string>Egypt</string></value>
<value><boolean>0</boolean></value>
<value><i4>-31</i4></value>
</data>
</array>
Элементы <array> не имеют имен.
Вы можете мешать типы как в примере приведенном выше.
<arrays>s могут быть рекурсивными, каждое значение может содержать <array> или любой другой тип, включая <struct>, описанную выше.
Пример ответа
Вот пример ответа на 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>
Формат ответа
Даже если есть ошибка уровня ниже, всегдпа возвращает 200 OK.
Поле Content-Type – text/xml. Content-Length должно присутствовать и должно біть корректным.
Тело ответа – это простая XML-структура: <methodResponse>, который может содержать один <params> который содержит <param> который содержит одно <value>.
<methodResponse> может также содержать элемент <fault> который содержит <value> которое является <struct> содержащей два элемента, один называется <faultCode> типа <int>,а другой – <faultString> типа <string>.
<methodResponse> не может содержать одновременно <fault> и <params>.
Пример ошибки 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>
Стратегии/Цели
Firewalls. Цель этого протокола проложить фундамет совместимый с различными средами. Firewall'ы могут просматривать запросы POSTs чьи поля Content-Type содержат text/xml.
Понятность. Мы хотели создать чистый, расширяемый, фомат который будет очень простым. Это даст возможность для HTML-декодера просматривать файл содержащий вызов XML-RPC процедуры, понять что он вызывает, стать способным модифицировать его дать возможность работать на первую или вторую попытку.
Простой в для использования. Мы также хотели чтобы это был простой для выполнения протокол, который может быть быстро адаптированный к другим средам или на других операционных системах.
© Copyright 1998-99 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.