レベル: 中級 Alex Rodriguez, Software Engineer, IBM
2008年 11月 06日 REST (Representational State Transfer) は SOAP ベースや WSDL (Web Services Description Language) ベースの Web サービスに代わる単純な手段として Web 全体で広く受け入れられるようになっています。こうした、インターフェース設計での REST へのシフトの重要な証拠として、Web 2.0 サービスを提供する主要各社 (Yahoo、Google、Facebook など) は SOAP ベースや WSDL ベースのインターフェースを非推奨あるいは不使用とし、使いやすいリソース指向のモデルを使って彼らのサービスを公開するようになっています。この記事では、Alex Rodriguez が REST の基本的な原則を紹介します。
基本
システムのリソースに焦点を当てた Web サービスを設計する際には、REST によって定義された一連のアーキテクチャーの原則に従った設計をすることができます。そうした原則には、さまざまな言語で作成された広範な種類のクライアントが HTTP を介してリソースの状態にアクセスし、転送するための方法も含まれています。REST を使用する Web サービスの数を見ると、この数年だけでも REST は Web サービスの設計モデルとして優勢なものになっています。実際、REST は SOAP ベースや WSDL ベースのインターフェース設計にほとんど取って代わるほど Web に大きな影響を与えましたが、それは REST のスタイルが比較的使いやすいためです。
REST は 2000年にカリフォルニア大学 Irvine 校 (University of California, Irvine) の Roy Fielding による博士論文「Architectural Styles and the Design of Network-based Software Architectures」の中で最初に紹介されましたが、その時には REST はそれほど注目されませんでした (この論文は、分散コンピューティングのプラットフォームとして Web を使用するソフトウェア・アーキテクチャーの一連の原則を分析しています (この論文へのリンクは「参考文献」を参照))。REST が紹介されてから何年も経っていますが、現在は REST のための主なフレームワークが登場し始め、現在も開発が続いていますが、これは例えば REST が JSR-311 によって Java™ 6 の必須部分になろうとしているためです。
この記事では、今日のように REST が非常に注目されている中で REST Web service の最も純粋な形での具象実装は、次の 4 つの基本的な設計原則に従うようにすることを提言します。
- 明示的に HTTP メソッドを使う
- ステートレスにする
- ディレクトリー構造に似た URI を公開する
- XML、JSON (JavaScript Object Notation) のいずれか、またはその両方を転送する
以下のセクションでは、これらの 4 つの原則について詳細に説明し、なぜこれらの原則が REST Web サービスの設計者にとって重要なのかという技術的な根拠を示します。
明示的に HTTP メソッドを使う
RESTful Web サービスの重要な特徴の 1 つは、RFC 2616 による HTTP プロトコルの定義に従って明示的に HTTP メソッドを使うことです。例えば HTTP GET は、クライアントの要求に一致する一連のリソースを Web サーバーが探し出して応答してくれるという期待の下に定義されたデータ生成メソッドで、クライアント・アプリケーションによって、リソースの取得や Web サーバーからのデータの取得、クエリーの実行などに使われることを目的としています。
REST では明示的に HTTP メソッドを使う必要があり、しかも HTTP プロトコルの定義どおりの方法で使う必要があります。この、REST での基本的な設計原則によって、CRUD (create、read、update、delete) 操作と HTTP メソッドとが 1 対 1 に対応付けられることになります。この対応付けに従うと、
- サーバー上にリソースを作成するためには POST を使います。
- リソースを取得するためには GET を使います。
- リソースの状態を変更、または更新するためには PUT を使います。
- リソースを除去、または削除するためには DELETE を使います。
残念なことに、多くの Web API に特有の設計上の欠陥は、HTTP メソッドが本来意図されていない使われ方をすることにあります。例えば HTTP GET リクエストのリクエスト URI は、通常は 1 つの具体的なリソースを特定します。あるいはリクエスト URI のクエリー・ストリングには検索条件を定義するパラメーター・セットが含まれていて、サーバーはこれらのパラメーター・セットを使うことで検索条件に一致する一連のリソースを見つけます。少なくとも、HTTP/1.1 RFC では GET についてそのように記述しています。しかし、HTTP GET を使ってサーバー上で何らかのトランザクションを開始する (例えばデータベースにレコードを追加するなど) という、美しくない Web API の事例が数多くあります。こうした場合には、GET リクエストの URI は適切に使われていないか、あるいは少なくとも RESTful に使われていません。Web API が GET を使ってリモート・プロシージャーを呼び出そうとすると、次のようになります。
GET /adduser?name=Robert HTTP/1.1
これはあまり美しい設計ではありません。上記の Web メソッドは HTTP GET を使って状態を変化させようとしているからです。別の言い方をすれば、上記の HTTP GET リクエストには副作用があります。このリクエストが適切に処理されると、そのリクエストの結果として新しいユーザー (この場合には Robert) がデータ・ストアに追加されることになります。この場合の問題は、主に GET の動作が持つ意味にあります。Web サーバーは、HTTP GET リクエストを受け取ると、リクエスト URI の中にあるパス (つまりクエリー条件) に一致するリソースを取得し、そうしたリソースやリソース表現をレスポンスに入れて返すように設計されており、データベースにレコードを追加するようには設計されていません。つまり HTTP プロトコルのメソッドで想定されている使い方の観点から見ても、HTTP/1.1 に準拠した Web サービスの観点から見ても、こうした GET の使い方は規格外です。
GET の動作が持つ意味の問題以外にも、GET に関するもう 1 つの問題として、GET によってデータベースのレコードの削除や変更、追加をトリガーしたり、GET によって何らかの方法でサーバー・サイドの状態を変更できるようにしたりすると、Web キャッシング・ツール (クローラー) や検索エンジンが単にリンクをクローリングするだけで、気づかないうちにサーバー・サイドの変更が行われてしまうという問題があります。この一般的な問題を簡単に克服するためには、リクエスト URI の中にあるパラメーターの名前と値を XML タグの中に移します。その XML タグ (作成対象のエンティティーの XML 表現) を送信するためには、HTTP POST ボディーの中にそのタグを入れ、リクエスト URI にはそのエンティティーの親となる URI を指定します (リスト 1 と 2)。
リスト 1. 変更前
GET /adduser?name=Robert HTTP/1.1
|
リスト 2. 変更後
POST /users HTTP/1.1
Host: myserver
Content-Type: application/xml
<?xml version="1.0"?>
<user>
<name>Robert</name>
</user>
|
上記のメソッドは典型的な RESTful リクエストです。HTTP POST が適切に使われており、ペイロードはリクエストのボディーの中に含まれています。受信側でこのリクエストを処理するためには、ボディーの中に含まれているリソースを、リクエスト URI の中で指定されるリソース配下に置かれるものとして追加します (この例では新しいリソースを /users の子として追加する必要があります)。POST リクエストの中で指定されている、新しいエンティティーとその親との間の包含関係は、あるファイルがその親ディレクトリーの子であるのと似ています。クライアントはエンティティーとその親との関係を設定し、新しいエンティティーの URI を POST リクエストの中で定義します。
するとクライアント・アプリケーションは、少なくとも論理的にはそのリソースが /users の下にあることを利用して、新しい URI を使ってリソース表現を取得することもできます (リスト 3)。
リスト 3. HTTP GET リクエスト
GET /users/Robert HTTP/1.1
Host: myserver
Accept: application/xml
|
この方法では GET がデータの取得にのみ使用されるため、GET の使い方は明示的です。GET 操作に副作用があってはなりません。この性質は冪等 (べきとう) としても知られています。
HTTP GET によって更新操作を行っている場合 (リスト 4) には、上と同じように Web メソッドを変更する必要があります。
リスト 4. HTTP GET による更新
GET /updateuser?name=Robert&newname=Bob HTTP/1.1
|
このメソッドはリソースの name 属性 (またはプロパティー) を変更しています。こうした操作にはクエリー・ストリングを使用することができ、またリスト 4 は単純なクエリー・ストリングですが、このようにクエリー・ストリングをメソッド・シグニチャーとして使用するパターンは、複雑な操作に使用した場合には破綻しがちです。目標は明示的に HTTP メソッドを使用することなので、もっと RESTful な方法にするためには、HTTP GET ではなく HTTP PUT リクエストを送信することでリソースを更新します。この理由は上と同じです (リスト 5)。
リスト 5. HTTP PUT リクエスト
PUT /users/Robert HTTP/1.1
Host: myserver
Content-Type: application/xml
<?xml version="1.0"?>
<user>
<name>Bob</name>
</user>
|
PUT を使って元のリソースを置き換える方法は、GET を使うよりもずっと正当なインターフェースの使い方であり、REST の原則にも HTTP メソッドの定義にも沿っています。リスト 5 の PUT リクエストは、更新が必要なリソースを PUT リクエストが指定する手段として、リクエスト URI の中で指定しているという意味では明示的であり、またリクエスト URI 上にパラメーターの名前と値の組み合わせを漫然と並べることでリソース属性を転送するのではなく、リソースの新しい表現を PUT リクエストのボディーの中でクライアントからサーバーに転送しているという意味でも明示的です。
またリスト 5 ではリソースの名前を Robert から Bob に変更しており、そのためにリソースの URI を /users/Bob に変更しています。REST Web サービスでは、このように変更した後で古い URI を使ってリソースを要求するリクエストを送信すると、標準的な 404 Not Found エラーが生成されます。
一般的な設計原則として、HTTP メソッドを明示的に使うという REST のガイドラインに従うためには、URI の中では動詞ではなく名詞を使う方が賢明です。RESTful Web サービスでは、動詞 (POST、GET、PUT、DELETE) はプロトコルの中で既に定義されています。そして理想的には、インターフェースを一般的なものに維持するために、またクライアントにとって呼び出す操作が明らかになるように、Web サービスは他の動詞やリモート・プロシージャー (/adduser や /updateuser など) を定義すべきではありません。この一般的な設計原則は HTTP リクエストのボディーにも当てはまります。HTTP リクエストのボディーはリソースの状態の転送用に使われることを想定しており、リモート・メソッドやリモート・プロシージャーを呼び出すための名前を送信するために使われることは想定していないのです。
ステートレスにする
REST Web サービスは、より高いパフォーマンスを求める要求に応えるために、スケーラブルでなければなりません。ロード・バランシングやフェールオーバー機能を備えたサーバー・クラスターやプロキシー、ゲートウェイなどは通常、サービス・トポロジーを構成するように配置されます。そうすることでリクエストは必要に応じてサーバー間で転送され、Web サービスの呼び出しに対する全体としての応答時間が短縮されます。仲介用のサーバーを使ってスケーラビリティーを改善するためには、REST Web サービスのクライアントは完全かつ独立したリクエストを送信する必要があります。つまり必要なデータをすべて含んだリクエストを送信する必要があり、そうすることによって仲介サーバーのコンポーネントは、リクエストから次のリクエストまでの間、ローカルで状態を保持しておかなくても、転送やルーティング、ロード・バランシングを行うことができます。
完全かつ独立したリクエストであれば、サーバーはそのリクエストを処理する際に、アプリケーションのいかなるコンテキスト、つまり状態をも取得する必要がありません。REST Web サービスのアプリケーション (つまりクライアント) は、サーバー・サイドのコンポーネントがレスポンスを生成するために必要とするすべてのパラメーターやコンテキスト、データを、リクエストの HTTP ヘッダーとボディーの中に含めます。このようにステートレスにすることで Web サービスのパフォーマンスが改善され、サーバー・サイドのコンポーネントの設計や実装が単純なものになります。なぜならサーバー上に状態が保持されないため、セッション・データと外部のアプリケーションとの同期が必要なくなるからです。
図 1 に示すステートフルなサービスを利用するアプリケーションでは、複数ページから成る結果セットをどこまでナビゲートしたのかを Web サービスが追跡していることを前提にして、結果セットの次のページを要求することができます。このステートフルな設計では、サービスは次のリクエストに応答できるように previousPage 変数をインクリメントしてどこかに保存します。
図 1. ステートフルな設計
こうしたステートフルなサービスは複雑になりがちです。Java EE (Java Platform, Enterprise Edition) 環境でステートフルなサービスを実現するためには、Java EE コンテナーのクラスター間でセッション・データの同期を取って効率的に保存する方法をあらかじめ十分に検討する必要があります。このような環境では、サーブレットや JSP (JavaServer Pages)、EJB (Enterprise JavaBeans) の開発者にはおなじみの、セッションをコピーする際に java.io.NotSerializableException が起こる根本原因の追求に苦労するという問題が起こります。この java.io.NotSerializableException 例外が、サーブレット・コンテナーが HttpSession をコピーする際にスローされるにせよ、EJB コンテナーがステートフルな EJB をコピーする際にスローされるにせよ、開発者はこの問題を解決するために、サーバーの状態を構成するオブジェクト群のグラフ (場合によると非常に複雑です) の中から、Serializable を実装していない 1 つのオブジェクトを特定しようとして何日もかける羽目になります。しかもセッションの同期を取るためのオーバーヘッドが追加され、それがサーバーのパフォーマンスに影響を与えます。
それとは対照的に、ステートレスなサーバー・サイド・コンポーネントをロード・バランシングされたサーバー全体にわたって設計、作成、分配する場合には、それほど複雑にはなりません。ステートレス・サービスでは高いパフォーマンスが得られるだけではなく、状態を維持するための作業の大部分がクライアント・アプリケーションに移されます。RESTful Web サービスでは、サーバーはレスポンスを生成し、クライアント・サイドでアプリケーションの状態を保持できるようにするためのインターフェースを提供します。例えば複数ページから成る結果セットを要求するリクエストでは、クライアントは単純に次のページを要求するのではなく、取得する必要のある実際のページ番号をリクエストの中に含める必要があります (図 2)。
図 2. ステートレスな設計
ステートレスな Web サービスが生成するレスポンスには、複数ページの結果セットの中の次ページ番号へのリンクが含まれており、クライアントがこのページ番号を保持するために必要なことを行えるようになっています。RESTful Web サービスの設計に関するこうした側面は、上位レベルで 2 つの部分に分割することができ、それによってステートレスなサービスを維持するための方法を明確にすることができます。
サーバー
- サーバーが生成するレスポンスには他のリソースへのリンクが含まれており、それによってアプリケーションは関連リソースの間をナビゲートすることができます。このいったレスポンスにリンクが埋め込まれているのと同様に、親リソースやコンテナー・リソースへのリクエストに対する典型的な RESTful レスポンスには、(リソース同士の関係を維持するために) その親の子供達や従属リソースへのリンクが含まれている可能性があります。
- サーバーが生成するレスポンスには、このレスポンスをキャッシュしておくことで、重複するリソースへのリクエストの数を削減したり、あるいは一部のリクエストを完全に削除したりして、パフォーマンスを改善することができるかどうかが示されています。サーバーはそのために、HTTP レスポンス・ヘッダーに Cache-Control と Last-Modified (日付の値) を含めます。
クライアント・アプリケーション
- クライアント・アプリケーションは Cache-Control レスポンス・ヘッダーを使用して、そのリソースをキャッシュする (ローカル・コピーを作る) かどうかを判断します。またクライアントは Last-Modified レスポンス・ヘッダーを読み取り、日時の値を If-Modified-Since ヘッダーに入れて返送することで、そのリソースが変更されているかどうかをサーバーに尋ねます。これは条件付きの GET (Conditional GET) と呼ばれ、この 2 つのヘッダー (Last-Modified と If-Modified-Since) は密接に関係しています。つまり要求された実際のリソースが指定の時刻から変更されていなければ、サーバーのレスポンスは標準的な 304 コード (Not Modified) であり、そのリソースはそのレスポンスに含まれません。HTTP 304 レスポンス・コードの意味は、リソースが変更されるまで、クライアントはリソース表現のローカル・コピーをキャッシュしたものを最新のものとして安全に使用することができ、実質的にその後の GET リクエストをバイパスできるということです。
- クライアント・アプリケーションは、他のリクエストとは独立してサービス可能な、完全なリクエストを送信します。そのためには、クライアントは Web サービスのインターフェースで指定された HTTP ヘッダーを完全利用する必要があり、また完全なリソース表現をリクエスト・ボディーの中に入れて送信する必要があります。クライアントはリクエストを送信する際、それ以前にどのようなリクエストが行われたか、サーバー上にセッションがあるかどうか、サーバーがリクエストにコンテキストを追加できるかどうか、リクエストとリクエストの間で保持されているアプリケーションの状態について、ほとんど前提を考慮しません。
RESTful Web サービスをステートレスにするためには、クライアント・アプリケーションとサービスの間での、こうした協調動作が必須です。こうした協調動作によって帯域幅が節約され、またサーバー・サイドで保持されるアプリケーションの状態が最小限になるため、パフォーマンスを改善することができます。
ディレクトリー構造に似た URI を公開する
リソースにアクセスするクライアント・アプリケーションの観点から見ると、REST Web サービスがどの程度直感的なものになるか、また設計者の想定どおりに使われるかどうかは、URI によって決まります。RESTful Web サービスの 3 番目の特徴として、URI に関する詳細を調べてみましょう。
REST Web サービスの URI は、容易に推測できるように直感的なものでなければなりません。URI は一種の自己記述型インターフェースと考えることができ、その URI が指すものを開発者が理解して関連するリソースを得る上では、説明や参照を (あったとしても) ほとんど必要としないものです。そのためには、URI の構造は単純かつ予測可能で、容易に理解できるものでなければなりません。
こうしたレベルの使いやすさを実現するための 1 つの方法は、ディレクトリー構造に似た URI を定義する方法です。このタイプの URI は階層構造を持ち、1 つのパス上にルートがあり、そのパスから、サービスのメイン領域を公開するサブパスが分岐しています。この定義に従うと、URI は単にスラッシュで区切られたストリングではなく、ノードに接続された下位分岐と上位分岐を持つツリーです。例えば、Java から論文までの広範なトピックを集めた議論用のスレッド・サービスでは、次のような構造の URI セットを定義することができます。
http://www.myservice.org/discussion/topics/{topic}
/discussion というルートの下には /topics ノードがあります。その下には一連のトピック名 (gossip、technology など) があり、それぞれが議論のスレッドを指しています。この構造の中では、/topics/ の後に何かを入力するだけで議論のスレッドを容易に拾い出すことができます。
場合によると、あるリソースへのパスがディレクトリー風の構造に特に適している場合があります。例えば日付で整理されているリソースを考えてみてください。こうしたリソースは階層構造の構文に最適です。
次の例はルールに基づいているため直感的です。
http://www.myservice.org/discussion/2008/12/10/{topic}
最初のパス部分は 4 桁で表現した年であり、2 番目のパス部分は 2 桁で表現した日付であり、3 番目のパス部分は 2 桁で表現した月です。このように説明するのは馬鹿げているように思えるかもしれませんが、私達が求めているのはこのレベルの単純さなのです。このような構造の URI はルールに基づいているため、人間もマシンもこうした構造化された URI を容易に生成することができます。URI には、URI を構成するための明確なパターンがあるため、構文スロットのパス部分を埋めると次のように適切な URI になります。
http://www.myservice.org/discussion/{year}/{day}/{month}/{topic}
RESTful Web サービスのための URI の構造を考える際には、他にもあるいくつかのガイドラインに留意する必要があります。
- サーバー・サイドのスクリプト技術を示すファイル拡張子 (.jsp, .php, .asp) がある場合には、それを隠し、別の何かに移植する際に URI を変更する必要がないようにします。
- すべての文字を小文字にします。
- 空白はハイフンまたはアンダーバー (のいずれか) で置き換えます。
- 可能な限りクエリー・ストリングを避けます。
- リクエスト URI が部分パスである場合には 404 Not Found コードを使わず、代わりにレスポンスとして必ずデフォルトのページ、またはリソースを提供します。
また、URI を静的なものにする必要があります。そうすれば、リソースが変更された場合、またはサービスの実装が変更された場合にも、リンクは同じままです。こうすることでブックマークを付けられるようになります。また URI にエンコードされたリソース同士の関係が、それらのリソースが保存されている場所でのリソースの表現方法に依存しないようにすることも重要です。
XML または JSON、またはその両方を転送する
リソース表現は通常、クライアント・アプリケーションがそのリソースを要求した時点でのリソースの状態とリソースの属性を反映しています。この意味でリソース表現は、ある時点におけるスナップショットにすぎません。この単純な例としては、データベースの中のレコードの表現を考えることができます (このレコードは列名と XML タグとの間のマッピングで構成され、XML 要素の値には行の値が含まれています)。あるいはシステムにデータ・モデルがあるとすると、この定義によればリソース表現はシステムのデータ・モデルの中の何か 1 つに関する属性群のスナップショットです。REST Web サービスでは、こうしたものを提供する必要があります。
RESTful Web サービスを設計するための最後の制約事項は、データのフォーマットに関するものです。アプリケーションとサービスは、リクエストとレスポンスのペイロードの中で、あるいは HTTP ボディーの中でデータを交換します。データ・フォーマットを単純に、人間が読み取れる形で、関係がわかるようにすることで、非常に大きな効果が現れます。
データ・モデルの中のオブジェクト同士は通常、何らかの形で関係しています。このデータ・モデル・オブジェクト (リソース) 同士の関係は、それらのオブジェクトをクライアント・アプリケーションに転送する際のオブジェクトの表現方法に反映されている必要があります。例えば議論用のスレッド・サービスでは、結合されたリソース表現には議論の元となったトピックとその属性を含めることもでき、そのトピックに対するレスポンスへのリンクを埋め込むこともできます。
リスト 6. 議論用のスレッドの XML 表現
<?xml version="1.0"?>
<discussion date="{date}" topic="{topic}">
<comment>{comment}</comment>
<replies>
<reply from="joe@mail.com" href="/discussion/topics/{topic}/joe"/>
<reply from="bob@mail.com" href="/discussion/topics/{topic}/bob"/>
</replies>
</discussion>
|
そして最後に、クライアント・アプリケーションがそのアプリケーションに最適な特定のコンテンツ・タイプを要求できるように、サービスを構築する際には組み込みの HTTP Accept ヘッダーを利用する必要があります (HTTP Accept ヘッダーの値は MIME タイプです)。RESTful サービスで使用される一般的な MIME タイプをいくつか挙げたものが表 1 です。
表 1. RESTful サービスで使用される一般的な MIME タイプ
| MIME タイプ | コンテンツ・タイプ |
|---|
| JSON | application/json |
|---|
| XML | application/xml |
|---|
| XHTML | application/xhtml+xml |
|---|
これによってサービスは、さまざまな言語で作成された、さまざまなプラットフォーム上やさまざまな機器上で実行される多種多様なクライアントから利用できるようになります。MIME タイプと HTTP Accept ヘッダーを使用するメカニズムはコンテンツ・ネゴシエーションと呼ばれ、このメカニズムによってクライアントはクライアント自身にとって適切なデータ・フォーマットを選択することができ、またサービスとそのサービスを利用するアプリケーションとの間でのデータの結合を最小限にとどめることができます。
まとめ
REST が必ずしも適切な選択肢とは限りません。Web サービスを設計するための手段として REST の人気が高まっている理由は、SOAP ベースや WSDL ベースの Web サービスに比べ、REST は独自のミドルウェア (例えばアプリケーション・サーバーなど) に依存しないためです。また REST は初期のインターネット標準である URI、HTTP などに重点を置いているため、ある意味で REST は、Web が大規模なアプリケーション・サーバーの時代になる以前の状態への回帰と言えます。この記事での、いわゆる RESTful なインターフェース設計原則の検証からわかるように、XML over HTTP は強力なインターフェースであり、Ajax (Asynchronous JavaScript + XML) ベースのカスタム・ユーザー・インターフェースなどの内部アプリケーションからリソースへの接続を行い、リソースにアクセスし、そしてリソースを利用することが容易になります。実際、Ajax と REST との親和性が非常に高いため、REST への注目が最近非常に高まっているのです。
システムのリソースを RESTful API をとおして公開することによって、標準的なフォーマット設定のデータを使って多種多様なアプリケーションを柔軟な方法で提供することができます。それはまた、データを容易に組み合わせること (マッシュアップ) ができるシステムを構築する上で欠かせない統合要件を満たす上でも役に立ち、また基本となる一連の RESTful なサービスをベースにして Web サービスを構築したり、もっと大規模なサービスへと拡張したりする上でも役立ちます。この記事はごく基本的な部分に触れただけですが、これを元に REST についてさらに学ぼうと思われたようであれば幸いです。
参考文献 学ぶために
製品や技術を入手するために
議論するために
著者について  | 
| | Alex Rodriguez は IBM のソフトウェア・エンジニアであり、分散 Java 技術と REST Web サービスを中心とした業務を行っています。彼は JDK 1.1.7B 以来 Java のプログラミングを行ってきており、Java EE ベースのソフトウェアの設計と開発が専門です。 |
記事の評価
| 
