8 RESTful Webサービスの開発

この章では、Representational State Transfer (RESTful) Webサービスの概念を示し、Java API for RESTful Web Services (JAX-RS)を使用してRESTful Webサービスを開発および構成する方法について説明します。

この章の内容は次のとおりです。

RESTful Webサービスの概要
RESTful Webサービス・リクエストが作成および処理される仕組み
RESTful Webサービスの有効化
RESTful Webサービスのサポートの制限事項

RESTful Webサービスの概要

Representational State Transfer (REST)は、SOAPなどの追加メッセージング・レイヤなしで、標準化されたインタフェース(HTTPなど)を介してデータを送信する単純なインタフェースを記述するものです。RESTには、ステートレス・サービスを作成するための一連の設計ルールが用意されており、これらはリソース(特定の情報のソース)として表示されます。それぞれのリソースは固有のURIで識別できます。クライアントがURIを使用してリソースにアクセスすると、標準化された固定のメソッド・セットと、リソースの表示が返されます。クライアントは、新しい各リソース表示を使用してステートを転送します。

HTTPプロトコルを使用してRESTfulリソースにアクセスする際は、リソース識別子がリソースのURLとなります。そのリソースに対して実行する標準操作は、HTTPメソッドの1つ(GET、PUT、DELETE、POSTまたはHEAD)です。

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

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

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

HTTP Getリクエストの構築
HTTP Postリクエストの構築
RESTfulレスポンスの構築

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という名前の操作に対して定義されたリクエスト・メッセージを示しています。

例8-1 操作に対するGETリクエスト

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

このリクエストは、次のURLを指定したGETを使用して起動できます。

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

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

例8-2 GETリクエストから作成される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サービスに対して送信されるリクエスト・メッセージを示しています。

例8-3 document-literalのラップ操作に対するGETリクエストの例

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

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

例8-4 document-literalのラップ操作のXML定義

<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

注意:

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

HTTP Postリクエストの構築

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

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

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

たとえば、次のRESTfulリクエストは、例8-6のSOAPエンベロープにラップされます。

例8-5 RESTfulリクエスト

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

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

例8-6 RESTfulリクエストをラップするSOAPエンベロープ

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

RESTfulレスポンスの構築

RESTfulリクエストとして処理される(GETまたはPOST)リクエストに対するレスポンスも、RESTfulスタイルである必要があります。サーバーは、サーバー上のSOAPレスポンスをクライアントに送信する前に、RESTfulレスポンスに変換します。RESTfulレスポンスは、SOAP本体の最初の子要素をルート要素として持つXMLドキュメントになります。たとえば、次の例のSOAPエンベロープがサーバー上にあると想定します。

例8-7 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ヘッダーや添付ファイルは、クライアントに返送されません。

例8-8 RESTfulレスポンス

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

RESTful Webサービスの有効化

Oracle Enterprise Managerを使用してWebサービスを管理する際に、WebサービスをRESTful Webサービスとして有効化するには、次の図に示すように、「Webサービス・エンドポイント」ページの「構成」タブで「REST対応」を「True」に設定します。詳細は、Web Servicesのセキュリティおよび管理者ガイドのRESTful Webサービスの有効化または無効化に関する項を参照してください。

図8-1 RESTful Webサービスの有効化

「図8-1 RESTful Webサービスの有効化」の説明

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

次のリストは、OracleAS Web Servicesによる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サービスでの操作名には、マルチバイト・キャラクタは使用できません。