XML-RPC

První údaj v prvním řádku hlavičky požadavku indikuje druh dotazu, což je v případě XML-RPC vždy „POST“. Druhá položka nese informaci o umístění XML-RPC serveru (tzv. URI). Neexistuje žádný zvláštní požadavek na URI, může být zadáno třeba jen lomítko, nebo může být dokonce prázdné. Třetím údaj definuje verzi a druh protokolu – pro potřeby XML-RPC se používá „HTTP/1.0“. Další čtyři řádky se skládají vždy z názvu položky a hodnoty („název: hodnota“) a jsou povinné. První ze čtveřice – „User-agent“ – obvykle informuje druh a verzi implementace. Řádek „Host“ určuje adresu počítače, na kterém běží XML-RPC server. „Content-Type“ značí druh odesílaných dat, musí mít vždy hodnotu „text/xml“. „Content-length“ udává délku dokumentu a ta musí být správně určena.

 POST /server HTTP/1.0
 User-Agent: identifikace_klienta
 Host: xmlrpc.moje-domena.cz
 Content-Type: text/xml
 Content-length: pocet_znaku

Tělo požadavku musí uvozovat značka „<methodCall>“. Jedná se o párovou značku, jejímž uzavíracím ekvivalentem „</methodCall>“ je potřeba tělo, respektive celý dokument, ukončit. Uvnitř této značky se nachází párová značka „<methodName>“, udávající název volané procedury (volaná procedura nemusí být ve skutečnosti procedurou, lze stejně dobře jako proceduru volat například tabulku či sloupec tabulky v databázi, záleží na konkrétní implementaci XML-RPC). V názvu procedury se smí vyskytovat pouze velká a malá písmenka A-Z, číslice 0-9, podtržítko, tečka, pomlčka a lomítko. Zároveň podle specifikace záleží jen na serveru, jak se vypořádat se znaky v názvu procedury. Po značkách „<methodName>“ následuje seznam parametrů předávaných vzdálené proceduře (pokud tato nějaké vyžaduje, v opačném případě není nutné, dokonce ani povolené, je uvádět). Parametry se uvozují párovými značkami „<params>“, mezi něž lze vložit libovolný počet parametrů (slovem „libovolný“ míním, že specifikace jejich počet nikterak neomezuje, počet omezuje pouze definice procedury). Každý parametr je uzavřen mezi značkami „<param>“, v nichž se nachází jeho hodnota mezi značkami „<value>“ s volitelnou definicí datového typu (obecně se doporučuje datový typ uvádět vždy pro zlepšení čitelnosti nebo pro předejití chyb z nepozornosti). Pokud existuje definice parametru, musí být vnořena do značky „<value>“.

 POST /server HTTP/1.0
 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; cs-CZ; rv:1.9.0.11) Gecko/2009060215 Firefox/3.0.11 
 Host: xmlrpc.example.com
 Content-Type: text/xml
 Content-length: 314

 <?xml version="1.0"?>
 <methodCall>
   <methodName>trida.jmenoMetody</methodName>
   <params>
     <param>
       <value><int>250</int></value>
     </param>
     <param>
       <value><base64>WiBXaWtpcGVkaWUsIG90ZXbFmWVuw6kgZW5jeWtsb3BlZGll</base64></value>
     </param>
   </params>
 </methodCall>

První položka prvního řádku značí verzi protokolu (vždy HTTP/1.1), za ní následuje stavový kód, který má ve většině případů hodnotu 200 OK, což znamená, že server obdržel požadavek a posílá odpověď (jiný stavový kód může být vrácen například v případě, že serverová část je napsána v jazyce PHP, jenž se dost často zavádí jako modul do webového serveru Apache, ten může v případě chyby vyslat i jiný, než „200 OK“ stavový kód).

Řádek „Connection“ obsahuje hodnotu „close“, díky čemuž klient pozná, že pokud chce serveru opět vyslat požadavek, musí navázat nové připojení. „Content-Length“ opět udává délku dokumentu a taktéž vyžaduje korektní hodnotu. Pole „Content-type“, stejně jako v hlavičce požadavku, nabývá pouze hodnot „text/xml“. Řádek „Date“ předává informaci o době odeslání odpovědi a to ve formátu RFC 822, updatovaném RFC 1123, který je považován za internetový standard (existují ještě dva další formáty data a času, s nimiž si musí být případní klienti/servery schopní poradit; je to důsledek zpětné kompatibility mezi protokoly HTTP/1.0 a HTTP/1.1, přestože odpověď není možné odeslat jinak než v HTTP/1.1, tento protokol však umožňuje odesílat datum pouze ve zmíněném formátu RFC 822/RFC 1123). Poslední položka hlavičky, a sice položka „Server“, informuje o jménu serveru odesílajícího odpověď.

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:31:06 GMT
 Server: identifikace_serveru

Tělo odpovědi tvoří velice jednoduchá XML struktura – značky „<methodResponse>“, mezi kterými se, na rozdíl od dotazu, musí vyskytnout párová značka „<params>“. Taktéž uvnitř musí existovat alespoň jedna značka „<param>“ obsahující hodnotu, případně datový typ.

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:35:15 GMT
 Server: identifikace_serveru

 <?xml version="1.0"?>
 <methodResponse>
 	<params>
 		<param>
 			<value><string>Text odpovědi</string></value>
 		</param>
 	</params>
 </methodResponse>

Stejná jako hlavička odpovědi, protože chybová odpověď je také odpovědí, pouze se striktně definovanou strukturou těla.

Tělo chybové odpovědi se uvozuje značkami „<methodResponse>“ následovanými značkami „<fault>“ – jakýsi ekvivalent k „<param>“, ovšem bez vnějšího „<params>“. Uvnitř se nachází značka „<value>“ obsahující datový typ „struct“. Struct má zde dva členy, první – „faultCode“ – udává číslo chyby, „faultString“ v sobě nese textovou část chyby. Toto číslo ani text není definováno, pouze se musí dodržet datové typy, jinak záleží čistě na implementátorovi serveru, jaká čísla si pro chyby vymyslí (existuje rozšíření definující několik běžných chyb, má však pouze doporučující charakter, nikoliv závazný).

Důležité upozornění: odpověď, ať už běžná nebo chybová, smí obsahovat buď „<params>“, nebo „<fault>“. Jiné struktury nejsou přípustné a slovo „nebo“ je míněno ve vylučovacím smyslu (tzn. nemohou nastat obě možnosti zároveň).

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:35:15 GMT
 Server: identifikace_serveru

 <?xml version="1.0"?>
 <methodResponse>
 	<fault>
 		<value>
 			<struct>
 				<member>
 					<name>faultCode</name>
 					<value><int>32001</int></value>
 				</member>
 				<member>
 					<name>faultString</name>
 					<value><string>Text chyby</string></value>
 				</member>
 			</struct>
 		</value>
 	</fault>
 </methodResponse>

XML-RPC v základním rozšíření definuje šest jednorozměrných a dva vícerozměrné datové typy.

Tabulka 1: datové typy

Zdroj:

Poznámka: Integer se smí skládat pouze z číslic, případně znaménkem před číslem samotným, nesmí obsahovat mezeru. Double navíc obsahuje desetinnou tečku, zároveň ale jeho rozsah záleží na konkrétní implementaci. Typ string povoluje jakékoliv znaky kromě znaku „<“ (menší než) a „&“, tyto dva znaky se převádějí na příslušné entity „&lt;“ a „&amp;“. String lze také použít pro přenos binárních dat. XML-RPC neumí vyjádřit nekonečno, záporné nekonečno nebo NaN (not a number).

Značka „<array>“ obsahuje jediný blok ohraničený pomocí „<data>“. Vnitřek bloku je složen z libovolného počtu hodnot, každou z nich obklopují dříve popsané značky „<value>“. Hodnoty pole nemají názvy ani indexy, na druhou stranu mohou obsahovat další pole, nebo strukturu.

 <array>
 	<data>
 		<value><i4>8</i4></value>
 		<value><string>Pepa</string></value>
 		<value><boolean>false</boolean></value>
 		<value><double>2100.45</double></value>
 	</data>
 </array>

Druhým datovým typem je „struct“ (struktura), uvozený značkou „<struct>“, v jejímž těle lze uvést libovolný počet prvků „<member>“, z nichž každý nese informaci o jméně – „<name>“ – a o hodnotě – „<value>“. Obdobně jako pole, i struktura může být rekurzivní, tzn. že jako hodnota se dá uložit další struktura, nebo pole.

 <struct>
 	<member>
 		<name>prvniPolozka</name>
 		<value><string>Text prvni polozky</string></value>
 	</member>
 	<member>
 		<name>druhaPolozka</name>
 		<value><string>Text druhe polozky</string></value>
 	</member>
 </struct>