RESTful Webサービスの開発に関する概要

9.1 RESTfulなWebサービスの概要

REST (Representational State Transfer)とは、SOAPのように追加のメッセージ層を使用することなく、HTTPなどの標準化されたインタフェースでデータを転送するためのシンプルなインタフェースを記述したものです。

RESTは、リソース(特定の情報のソース)と見なされ一意のURIで特定できるステートレス・サービスを作成するための設計ルールのセットを提供します。クライアントはURI、標準化されたメソッドの固定セットを使用してリソースにアクセスし、リソースの表現が戻されます。クライアントは、新しいリソース表現を受け取るたびに転送状態に設定されます。

HTTPプロトコルを使用してRESTfulリソースをアクセスする場合、リソース識別子はリソースのURLであり、このリソースで実行される標準のオペレーションはHTTPの1つのメソッド(GET、PUT、DELETE、POST、またはHEAD)です。

RESTfulエンドポイントは、javax.xml.ws.Provider<T>インタフェースのinvoke()メソッドを使用して構築します(http://java.sun.com/javaee/5/docs/api/javax/xml/ws/Provider.htmlを参照)。Providerインタフェースは、サービス・エンドポイント・インタフェース(SEI)を構築するための動的な代替手段を提供します。

9.2 RESTful Webサービス・リクエストが作成および処理される仕組み

RESTful Webサービス・リクエストがクライアント側でどのように作成され、サーバー側でどのように処理されるかを、次の各項で詳細に説明します。

9.2.1 HTTP GETリクエスト

RESTful Webサービスは、HTTP GETリクエストをサポートします。RESTfulリクエストを開始するには、特定のURLでGETを使用します。

この項では、HTTP Getリクエストを作成する方法について説明します。内容は次のとおりです。

9.2.1.1 HTTP Getリクエストについて

たとえば、次のURLでREST対応のSOAPエンドポイントがデプロイされているとします。

http://example.com/my-app/my-service

この場合、次のURLでHTTP GETリクエストが受け入れられます。

http://example.com/my-app/my-service/{operationName}?{param1}={value1}&{param2}={value2}

この例では、{operationName}はサービスに対するWSDL内の操作名の1つです。RPC-literal操作の場合は、{param1}、{param2}などが、操作の入力であるwsdl:message内で定義される各部分の名前になります。ただし、これらの各部分はsimpleType(xsd:intなど)である必要があります。

注意:

ブラウザによっては、HTTP GET URLのサイズが制限されていることがあります(通常は2000文字未満)。パラメータ数を制限し、パラメータの名前と値を短くすることで、URLのサイズを小さくするように注意してください。

document-literal操作では、メッセージはパラメータを1つのみ持ちます。複数のパラメータをシミュレートするため、WSDLには、スキーマでsequenceとして定義されている1つのみのパラメータを指定します。sequenceの各メンバーをパラメータと考えることができます。この場合、{param1}、{param2}などが、message部分ではなくsequence型のメンバーになります。RPC-literalの場合と同様に、これらのメンバーはsimpleTypeである必要があります。

次の例は、addNumbersという名前の操作に対して定義されたリクエスト・メッセージを示しています。

<wsdl:message name="AddNumbersRequest"> 
      <wsdl:part name="a" type="xsd:int" /> 
      <wsdl:part name="b" type="xsd:int" />
</wsdl:Message>

9.2.1.2 HTTP Getリクエストの構築

RESTfulリクエストを開始するには、次のURLでGETを使用します。

http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24

次の例は、Oracle Web ServicesプラットフォームがGETリクエストからサーバー側で作成するSOAPエンベロープを示しています。このメッセージは、他の受信SOAPリクエストと同様に処理されます。

<soap:Envelope> 
    <soap:Body> 
        <ns:addNumbers> 
            <ns:a>23</ns:a> 
            <ns:b>24</ns:b> 
        </ns:addNumbers> 
    <soap:Body> 
<soap:Envelope>

次の例は、サービスがdocument-literal操作として定義されている場合にaddNumbersサービスに対して送信されるリクエスト・メッセージを示しています。

<wsdl:message name="AddNumbersRequest"> 
     <wsdl:part name="params" type="tns:AddNumbersRequstObject" />
</wsdl:Message>

次の例は、AddNumbersRequestObjectの定義を示しています。これはスキーマでも同じ定義になります。

<xsd:complexType name="AddNumbersRequestObject"> 
    <xsd:complexContent> 
        <xsd:sequence>
            <xsd:element name="a" type="xsd:int"/> 
            <xsd:element name="b" type="xsd:int"/>
        </xsd:sequence> 
    </xsd:complexContent> 
</xsd:complexType>

この操作は、次のURLを指定したGETリクエストによって起動できます。

http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24

注意:

これは、RPC-literalリクエストのaddNumbers操作の例に使用したものと同じURLです。

9.2.2 HTTP POSTリクエスト

RESTful Webサービスでは、単純なXMLメッセージのHTTP POSTリクエストはサポートされていますが、SOAPエンベロープのHTTP POSTリクエストはサポートされていません。

この項では、HTTP POSTリクエストを作成する方法について説明します。内容は次のとおりです。

9.2.2.1 HTTP Postリクエストについて

RESTful Webサービスでは、単純なXMLメッセージのHTTP POSTリクエストはサポートされていますが、SOAPエンベロープのHTTP POSTリクエストはサポートされていません。RESTfulリクエストでは、添付ファイル付きのメッセージはサポートされていません。このサービスではSOAPリクエストもサポートされているため、指定されたリクエストがSOAPまたはRESTfulのどちらであるかを実装側で判断する必要があります。

SOAPサービスは、POSTリクエストを受信するとSOAPアクション・ヘッダーを検索します。ヘッダーが存在する場合は、実装はこのリクエストをSOAPリクエストであると判断します。存在しない場合は、リクエストのroot要素のQNameが検索されます。それがSOAPエンベロープのQNameであれば、メッセージはSOAPリクエストとして処理されます。そうでない場合は、RESTfulリクエストとして処理されます。

9.2.2.2 HTTP Postリクエストの構築

RESTfulリクエストは、リクエスト・ドキュメントをSOAPエンベロープでラップすることで処理されます。SOAP 1.2リクエストのContent-TypeヘッダーではないHTTPヘッダーのみが、そのまま受信されます。このContent-Typeヘッダーは、SOAP 1.2用の適切なコンテンツ・タイプであるapplication/soap+xmlに変更されます。

たとえば、このRESTfulリクエストは、次のリクエストに示されているSOAPエンベロープにラップされます。

<ns:addNumbers> 
    <ns:a>23</ns:a> 
    <ns:b>24</ns:b> 
</ns:addNumbers>

次のリクエストは、通常のSOAPリクエストとして処理されます。

<soap:Envelope> 
       <soap:Body> 
               <ns:addNumbers> 
                       <ns:a>23</ns:a> 
                       <ns:b>24</ns:b> 
               </ns:addNumbers> 
           </soap:Body> 
</soap:Envelope>

9.2.3 RESTfulレスポンス

RESTfulリクエストとして処理される(GETまたはPOST)リクエストに対するレスポンスも、RESTfulスタイルである必要があります。

サーバーは、サーバー上のSOAPレスポンスをクライアントに送信する前に、RESTfulレスポンスに変換します。RESTfulレスポンスは、SOAP本体の最初の子要素をルート要素として持つXMLドキュメントになります。

たとえば、次の例のSOAPエンベロープがサーバー上にあると想定します。

<soap:Envelope>
    <soap:Body> 
        <ns0:result xmlns:nso="…"> 
            <ns:title>How to Win at Poker</ns:title> 
            <ns:author>John Doe</ns:author> 
        </ns0:result>
    </soap:Body>
</soap:Envelope>

次の例は、クライアントに返送されるレスポンスを示しています。Content-Typeが常にtext/xmlである点に注意してください。SOAPヘッダーや添付ファイルは、クライアントに返送されません。

<ns0:result xmlns:ns0="…"> 
       <ns:title>How to Win at Poker</ns:title> 
       <ns:author>John Doe</ns:author> 
</ns0:result>

9.3 RESTful Webサービスのサポートの制限事項の理解

Oracle Web Services support for RESTful Webサービスには、一定の制限があります。

次に制限事項について説明します。

RESTful Webサービスは、literal操作を含むWebサービス・アプリケーションに対してのみサポートされます(リクエストとレスポンスの両方がリテラルである必要があります)。
HTTP GETは、(必須の)複合パラメータのないWebサービス操作に対してのみサポートされます。
ブラウザによっては、HTTP GET URLのサイズが制限されていることがあります(通常は2000文字以下)。パラメータ数を制限し、パラメータの値と名前を短くすることで、URLのサイズを小さくするように注意してください。
RESTful Webサービスでは、簡易XMLメッセージのみが送信されます。添付ファイル付きメッセージは送信できません。
セキュリティや信頼性など、管理機能の多くは、RESTful Webサービスでは利用できません。これは、この情報の伝達に通常使用されるSOAPヘッダーが、サービスのRESTful起動では使用できないためです。
RESTful起動は、生成されたスタブまたはDIIクライアントから行うことはできません。それらのクライアントからの起動はSOAPで行われます。
プロバイダのフレームワークでは、RESTはサポートされません。
RESTful Webサービスでの操作名には、マルチバイト・キャラクタは使用できません。