XML-RPC 仕様書

Tue, Jun 15, 1999; by Dave Winer.

Updated 6/30/03 DW

Updated 10/16/99 DW

Updated 1/21/99 DW

Japanese translation Sun, May 9, 2003; by Yasushi Iwata

Japanese translation Updated Tue, Jul 29, 2003; by Yasushi Iwata

この仕様書は UserLand Frontier 5.1 に実装されている XML-RPC プロトコルについて述べたものです。

非技術者の向けの解説は XML-RPC for Newbies に書かれています。

このページには XML-RPC を実装するにあたって必要な内容のすべてが書かれています。

概要

XML-RPC はインターネット上でリモートプロシージャコールを実行するためのプロトコルです。

XML-RPC メッセージは HTTP-POST リクエストで、リクエストの body は XML です。プロシージャはサーバ側で実行され、その結果もまた XML 形式で返されます。

プロシージャのパラメータにはスカラー値、数値、文字列、日付等のほか、複合的なレコード/リスト構造で指定することができます。

リクエストの例

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>

ヘッダに必要な内容

ヘッダ最初の行の URI は特に規定していません。サーバ側が XML-RPC コールを処理できるのであれば、URI が指定されていなかったり、単に / となっていてもかまいません。しかし、サーバが XML-RPC 以外の HTTP リクエストも処理している場合、XML-RPC のコードを呼び出すための URI を指定することも可能です(例では URI が /RPC2 となっており、サーバに RPC2 という名前に対応するリクエストとして処理するよう告げています)。

User-Agent と Host は必ず指定しなければなりません。

Content-Type は text/xml です。

Content-Length も必須で正しい値を指定しなければなりません。

ペイロードのフォーマット

ペイロード(データ本体)は XML であり、単一の <methodCall> で構成されます。

<methodCall> は呼出すべきメソッド名の文字列をデータとして持つ副要素 <methodName> を含んでいなければなりません。使用できる文字はアルファベットの大文字と小文字、数字、アンダースコア、ドット、コロンおよびスラッシュです。mehodName にどんな文字列を指定すると、どのような内容が実行されるかは、サーバアプリケーションに依存します。

たとえば methodName はリクエストによって実行されるスクリプトのファイル名かもしれません。データベーステーブルのセル名かもしれません。あるいは、ファイルシステム上の特定のファイルのパス名かもしれません。

プロシージャコールにパラメータがある場合、<methodCall> は副要素 <params> を含んでいなければなりません。<params> はさらに複数の <param> 含み、各 <param> はそれぞれ単一の <value> を含みます。

<value> のスカラー値

<value> にはスカラー値を指定できます。その型は次の表にあるように、型を示すタグで囲んで指定します。

タグ	型	例
<i4> または <int>	4バイトの符号付き整数	-12
<boolean>	0 (偽) または 1 (真)	1
<string>	文字列	hello world
<double>	倍精度浮動小数点数	-12.214
<dateTime.iso8601>	日付と時刻	19980717T14:08:55
<base64>	base64 でエンコードされたバイナリ	eW91IGNhbid0IHJlYWQgdGhpcyE=

型の指定がない場合は string として扱われます。

<struct>

型の指定には <struct> を使うこともできます。

<struct> は複数の <member> を含み、各 <member> は <name> と <value> を1個づつ含みます。

以下は2つの要素を持つ <struct> の例です。

<struct>
   <member>
      <name>lowerBound</name>
      <value><i4>18</i4></value>
      </member>
   <member>
      <name>upperBound</name>
      <value><i4>139</i4></value>
      </member>
   </struct>

<struct> は再帰的な定義も可能で、<value> には <struct> や次に述べる <array> など、どのような型でも指定できます。

<array>

value の型には <array> を指定することもできます。

<array> は複数の <value> を含む1つの <data> 要素を含みます。

以下は4つの要素を持つ array の例です。

<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> は再帰的な定義が可能で、 value には <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>

レスポンスのフォーマット

XML-RPC より下のレベルでエラーが発生しない限り、常に 200 OK を返します。

Content-Type は text/xml です。Content-Length も必須で正しい値を返さなければなりません。

レスポンスの body は単一の XML で、単一の <methodResponse> から成ります。<methodResponse> は単一の <params> を含むことが可能で、<params> は単一の <param> を含み、<param> は単一の <value> を含みます。

<methodResponse> には単一の <fault> を含ませることも可能です。<fault> は単一の <value> を含み、その <value> は単一の <struct> を含み、<struct> は2つの要素 <faultCode> と <faultString> を含みます。<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>

方針と目標

ファイアウォール: このプロトコルが目指すのは、CGI インターフェースで提供されるもの以上の機能を使うことなく、異なる環境で互換性を持つ基盤を築くことです。ファイアウォールソフトウェアは、リクエストの Content-Type が text/xml であるかどうかだけをチェックすれば良く、それ以外を調べる必要はありません。
確認のし易さ: 我々が意図したのはクリーンで、拡張可能で、非常にシンプルなプロトコルです。HTML コーダなら誰でも、XML-RPC プロシージャコールに含まれるファイルを見て、何をするものなのか理解でき、必要な場合はそれを修正して、1、2度試しただけでちゃんと動かせるようなものを目指しました。
実装のし易さ: 異なる環境や異なるオペレーティングシステム用にもすぐに変更できて動かせる、実装し易いものを目指しました。

Updated 1/21/99 DW

Python で XML-RPC を実装するにあたっての次の質問が UserLand の掲示板に出されました。

レスポンスのフォーマットのセクションに「レスポンスの body は単一の XML で、単一の <methodResponse> から成ります。 <methodResponse> は単一の <params> を含むことが可能で...」とありますが、<params> を省略しても良いのですか？

プロシージャの実行が成功した場合、省くことはできません。レスポンスには <params> か <fault> のどちらか一方が含まれていなければなりません。「可能で」と書かれているのは、どちらか一方を指定できるという意味です。
"boolean" は単独のデータ型でしょうか？それとも整数に置き換え可能なものでしょうか？(例: 0は偽、非0は真など)

boolean は独立したデータ型です。言語/環境によっては、0を偽、1を真とみなすものもありますが、真を意図するときは、boolean 型の true を送るべきです。そうすることで、誤った解釈を避けられます。
整数の正しい表記と範囲はどのようになりますか？ほかの数字の前に0を付けても良いのですか？プラス記号を付けても良いのですか？スペースが含まれていても良いのでしょうか？

整数は32ビットの符号付き整数です。数字の前にはプラスかマイナスの記号を付けることができます。0以外の数字の前に0を付けても無視されます。スペースを含めてはいけません。数字の前に置くことができるのは、プラスかマイナスの記号だけです。
浮動小数の正しい表記はどのようになりますか？指数表記は可能ですか？スペースが含まれていても良いのですか？無限大や "not a number" は表記可能ですか？

無限大や負の無限大、"not a number" は表記できません。今のところ、プラスかマイナスの記号だけ数字の前に付けることができ、数字に続くピリオド、その後に数字が続く表記だけが可能です。スペースを含めてはいけません。範囲は実装依存で、定義していません。
使用可能な文字列は？表示できない文字やヌル文字は許されるのですか？"string" を使ってバイナリデータを保持させても良いのですか？

すべての文字が使えますが、< と & はそれぞれ < と & にエンコードしなくてはなりません。stirng をエンコードしたバイナリデータに使ってもかまいません。
"struct" 要素はキーの順序を保持するのでしょうか？つまり、struct で "foo=1, bar=2" とするのは "bar=2, foo=1" とした場合と同等なのでしょうか、違うのでしょうか？

struct 要素はキーの順序を保持しません。2つの struct は同等です。
<fault> 要素の struct に <faultCode> と <faultString> 以外の member を追加しても良いのでしょうか？グローバルな(Java や Python などの例外にマッピング可能な) faultCode の一覧はあるのでしょうか？
<fault> 要素の struct には、この仕様書でされていない member を 含めてはいけません。これは他のデータ構造に関しても同様です。仕様は充分フレキシブルで、一般的なデータ転送は定義された構造に従って処理可能なはずです。もしどうしても、そうではないという点があれば、掲示板の方へその内容を投稿してください。

グローバルな faultCode の一覧はありません。エラーはサーバアプリケーションに依存、もしくはこのプロトコルより上位にエラーを定義している標準規格があるためです。
dateTime.iso8601 型のタイムゾーンは何を想定すべきでしょうか？ UTC？それとも localtime？

タイムゾーンを勝手に想定してはいけません。タイムゾーンはサーバ側のドキュメントで、どのタイムゾーンを使用するか定義すべきものです。

追加

<base64> 型 1/21/99 DW.

Updated 6/30/03 DW

文字列の定義から "ASCII" を削除。

以下の著作権表示で 1998-99 となっていた部分を 1999-2003 に変更。

著作権と免責事項

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.