Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

WADL リファレンス

WADL 表記の基本的な形式を、簡単な例として以下に示します。WADL 表記では、API にある全リソースのベースパスを識別する <resources> 要素を最初に定義します。次に 1 つ以上の <resource> 要素を定義します。各要素では、API 内のリソースの情報を記述します。各 <resource> 要素定義には、メソッド、パラメータ、リソースの関連ドキュメントが含まれます。

WADL 表記から引用された以下の例には、1 つの <resources>要素が含まれており、API のために 1つのベースパスエンドポイントが定義されています。次に <resource> 要素が <resources> 要素内に定義されています。この <resource> 要素には、1 つ以上の <method> 定義が含まれており、この API リソースで使用可能なアクションが定義されています。一般的な WADL 表記では、API 内の各リソースに対応して、複数の <resource> 要素がこの後に続きます。

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:apigee="http://api.apigee.com/wadl/2010/07/"
             xmlns="http://wadl.dev.java.net/2009/02"
             xsi:schemaLocation="http://wadl.dev.java.net/2009/02 
                 http://apigee.com/schemas/wadl-schema.xsd 
                 http://api.apigee.com/wadl/2010/07/ 
                 http://apigee.com/schemas/apigee-wadl-extensions.xsd">
    <resources base="http://api.example.com/1">
        <resource path="statuses/public_timeline.{format}">
            <method>
                ...
            </method>
        </resource>
    </resources>    
</application>

WADL の要素

これ以降のセクションでは、WADL 要素ごとに参照情報を提供します。次のような情報があります。

  • 要素が必須であるかどうか
  • 指定する必要がある、または指定できる要素のインスタンス数
  • 要素の属性の名前と説明、および子要素の名前と説明
  • 要素の例
  • 要素の説明

<resources> 要素

必須。WADL の仕様ごとに 1 つ以上の <resources> 要素が必須とされます。

属性

Name 説明
base エンドポイントのベースパス

子要素

Name 説明
<resource> API リソースの説明

<resources base="http://api.example.com/v1">

説明

WADL の仕様ごとに少なくとも 1 つの <resources> 要素を含めます。<resources> 要素には、エンドポイントのドメインとベースパスを定義する 1 つの属性 base を含めます。各 <resources> 要素には、通常、複数の <resource> 要素が含まれます。

API に複数のエンドポイントがある場合、各エンドポイントに対して 1 つの <resources> 要素を含める必要があります。各 <resources> 要素内では、ベース URL の下にある <resource> 要素を指定します。例えば、API において、http://api.example.com/search/v1 で 1 つのエンドポイントを指定し、http:api.example.com/community/v1 で別のエンドポイントを指定できます。この API の WADL 表記には、2 つの <resources> 要素が含まれ、それぞれに対応するベース URL が指定されます。

<resource> 要素

必須。<resources> 要素ごとに 1 つ以上の <resource> 要素が必須とされます。

属性

Name 説明
path リソースへのパス

子要素

Name 説明
<param> このリソースへのリクエストに使用されるパラメータを指定します。
<method> このリソースに関連付けられるメソッドを定義します。
<apigee:choice>   <param> 要素の選択肢を指定します。
<resource path="statuses/public_timeline.{format}">
    <param> ... </param>
    <param> ... </param>
    <method> ... </method>
</resource>

説明

API 内の各リソースについては、WADL ファイル内の <resource>要素で説明を記述します。<resource> 要素には、このリソースへのパスを指定する path 属性があります。path 属性の値は固定値にすることができます。また、組み込みのテンプレートパラメータ (上記の例の {format} など) を含めることもできます。

リソースの完全なパス名は、<resources> 要素の base 属性値と <resource> 要素の path 属性値を連結して生成されます。またこの例の {format} のように、テンプレートパラメータは、Console でユーザーが入力した値 (または、定義されている場合はデフォルト値) に置き換えられます。この例では、このリソースの完全なパス名は次のとおりです。

<resource> 要素には、パラメータを定義する省略可能な <param> 要素を 0 個以上含めることができます。含めた場合、これらのパラメータは、この <resource>要素の一部として定義されたメソッドで使用されます。また <resource> 要素には、省略可能な <apigee:choice> 要素も含めることができます。これは、パラメータの選択肢を複数定義します。詳細については、「<apigee:choice> 要素」を参照してください。

注記: <resource> 要素に <param> 要素を含める場合、これらの要素は、WADL 表記内で <method> 要素の前に指定する必要があります。<method> 要素の後に <param> 要素を指定すると、WADL を Apigee にアップロードするときにエラーが発生します。また <param> 要素は、<request> 要素の一部として、<method> 要素の宣言内に含めることができます。前者のアプローチでは、すべてのメソッドが <param> 要素を継承します。対照的に、メソッドに <param> 要素を含める場合、パラメータはこのメソッドのスコープに限定されます。

一般的に、各リソースには 1 つの <method> 要素が含まれています。ただし、同じパスを共有するが、複数の動詞があるリソースには、WADL 表記で複数の <method> 要素を指定できます。例えば、1 つのリソースに GET と POST の両方のメソッドを指定できます。この場合、1 つの <resource> 定義に 2 つの <method> 定義 (1 つの動詞に 1 つ) を含めることができます。

<param> 要素

省略可能。<resource> または <request> 要素には、<param> 要素を 0 以上含めることができます。

属性

Name 説明
name パラメータ名
required パラメータが必須 (true) であるか、省略可能 (false) であるかを示します。デフォルトは false です。
type パラメータの予想される XML スキーマデータ型 (例えば、xsd:string)
style パラメータの予想されるタイプ (例えば、query または header)
default パラメータのデフォルト値

子要素

Name 説明
<doc> パラメータのテキストの説明
<option> パラメータで選択できる値のセット

<param name="count" required="false" type="xsd:string" default="5">
    <doc>取得するレコード数を指定します。
          200 以下にする必要があります。</doc>
</param>

説明

<resource> 要素には、省略可能な <param> 要素 を 0 個以上含めることができます。後者の要素は、当該リソースへのリクエストに使用されるパラメータを説明します。パラメータは、Console の対応するタブでタイプ (query、template、headers) 別に分類され、WADL ファイルに表示される順序でリストされます。

注記: <param> 要素は、<request> 要素にも含めることができます。

<param> 要素には、以下の属性と子要素が含まれます。

  • name

    name 属性は、パラメータ名を指定します。この値は、Console のパラメータリストに表示されます。特定のメソッドの全パラメータ名は、スコープ内で一意にする必要があります (例えば、そのメソッド内で)。

  • required

    required 属性は、パラメータが必須の場合は true に、パラメータが省略可能である場合は false に設定する必要があります。Console では、必須のパラメータには赤いアスタリスクが付けられます。デフォルト値は、default 属性を使用して指定できます。

    例えば、以下の例では、type という名前のパラメータは必須であり、デフォルト値は text になります。パラメータ自体と「Query」タブの両方に赤いアスタリスクが付けられ、これらが必須であることが示されています。

    パラメータの required 属性

    注記: 現在、Apigee Console では、ユーザーは required パラメータなしでリクエストを送信できます。したがって、意図的にこれらのリクエストを失敗にすることができます。この操作は、特定の条件下でどのようなエラーが発生するかを確認するために役立ちます。さらに、Console には、エラーを修正するためにユーザーが何をすべきかが明確に示されます。

  • type

    type 属性は、パラメータの予想されるタイプを指定します。有効値は、標準的な XML Schema データ型の定義済みセットに含まれる任意の値です。値の例としては、xsd:stringxsd:booleanxsd:integer が挙げられます。

  • style

    style 属性は、パラメータのタイプを指定します。有効値には、queryheader、template などがあります。

    パラメータは、Console UI の対応するタブの下に表示され、WADL に表示される順序でリストされます。

  • default

    省略可能な default 属性は、このパラメータのデフォルト値を指定します。デフォルト値が含まれている場合、ユーザーがそのリソースを選択すると、その値が Console に表示されます。パラメータが必須である場合、Console では、そのパラメータの値フィールドにデフォルト値が自動的に入力されます。

    パラメータが省略可能である場合、Console には、デフォルト値がプレースホルダテキストとして表示され、後に (example) というテキストが続けて表示されます。ユーザーが省略可能なパラメータの値を入力すると、グレー表示のテキストは、ユーザーが選択した値に置き換えられます。次の例では、デフォルト値が 200 になっている省略可能パラメータ count を示します。

    オプションのパラメータ

  • <doc>

    <doc> 要素は省略可能ですが、推奨されています。この要素には、このパラメータについて説明する書式なしテキストのドキュメントが含まれます。このドキュメントは、パラメータ名と値フィールドに関連付けられて Console に表示されます。省略可能な apigee:url 属性には、その他のドキュメントの URL が含まれ、これは Console では詳細情報へのリンクとして表示されます。

    注記: <doc> 要素では書式なしのテキストのみがサポートされます。

    例えば、WADL ファイルのエントリを次に示します。

    <param name="limit" type="xsd:positiveInteger" style="query" required="false" default="20">
        <doc apigee:url="http://www.tumblr.com/docs/en/api/v2#blog-followers">
            <![CDATA[ 返す結果の数: 1-20 (これらの値は含まれます) ]]>
        </doc>
    </param>

    次の Console UI が生成されます。

    次の <doc> 要素の場合:

    <doc apigee:url="http://www.tumblr.com/docs/en/api/v2#hostname"></doc>

    Console UI では、詳細情報へのこのデフォルトリンクが生成されます。

    パラメータの doc 要素

  • <option>

    また <param> 要素には、パラメータで選択できる値セットを列挙する <option> 要素も含めることができます。すべてのオプション値は、特定のパラメータに対して一意にする必要があります。例えば、次の query-style パラメータには、いくつかのオプションが定義されています。

    <param name="object" type="xsd:string" style="query" required="false" default="post">
        <option value="post"/>
        <option value="user"/>
        <option value="page"/>
        <option value="event"/>
        <option value="group"/>
        <option value="checkin"/>
    </param>

    WADL 表記に特定パラメータのオプションが複数含まれている場合、これらのオプションは、ドロップダウンメニューとして Console に表示されます。パラメータが必須ではない場合、ユーザーがパラメータの指定を省略できるように、ドロップダウンメニューには、オプション「(blank)」 も表示されます。オプションは、WADL ファイルに表示される順序でメニューにリストされます。例:

    パラメータオプションのドロップダウンメニュー

<method> 要素

必須。<resource> 要素ごとに 1 つ以上の <method> 要素が必須とされます。

属性

Name 説明
id このメソッドの一意の識別子
name 使用する HTTP メソッドのタイプ (GET、POST、DELETE、または PUT)
apigee:displayName Apigee Console でのメソッドの表示名

子要素

Name 説明
<apigee:tags> Apigee Console 内のメソッドの整理に使用します。
<apigee:authentication> 認証が必須であるかどうかを指定します。
<doc> <doc> Apigee Console でメソッドにマウスポインタを重ねると表示されるツールチップテキストを指定します。指定する場合、<doc> 要素は <request> 要素よりも前に指定する必要があります。
<request> メソッドに渡される 1 つ以上の <param> 要素を指定します。<doc> 要素を指定する場合、<request> 要素は <doc> 要素の後に指定する必要があります。
<response> Apigee は、<method> 要素の <response> 子要素をサポートしません。

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    <apigee:tags>
        <apigee:tag primary="true">Timeline</apigee:tag>
    </apigee:tags>
    <apigee:authentication required="false" />
</method>

説明

<method> 要素は、API にある個々のメソッドと関連付けられ、id および name 属性で記述されます。WADL 表記の各 <method> 要素には、一意の ID が必要です。name 属性は、使用される HTTP メソッドのタイプ (GET、POST、DELETE、または PUT) を指定します。

また各 <method> 要素には、apigee:displayName 属性で指定される省略可能な表示名が含まれます。表示名には、Console のメソッドリストに表示されるテキストが含まれます。表示名が指定されていない場合、<resource> 要素の path 属性がメソッド名として Console に表示されます。

また各メソッドには、標準的な WADL の Apigee 拡張として <apigee:tags><apigee:authentication> が含まれます。これらの Apigee 拡張は各メソッドの宣言のために必要です。さらにこれらの拡張は、厳密に <apigee:tags> <apigee:authentication> という順序で WADL に含める必要があります。

タグにより、メソッドはグループ別に分類できます。Console では、メソッドは定義されたタグでグループ分けされ、ナビゲーションがしやすくなっています。このようにタグはメソッドのカテゴリとしての役割を果たします。タグは Console でアルファベット順に表示されます。タグで整理されるメソッドは、WADL に定義されている順序で表示されます。

注記: タグ要素に true に設定されたプライマリ属性が含まれていない場合、メソッドは Console のメソッドリストに表示されません。また複数のタグ要素に true に設定されたプライマリ属性が含まれている場合、WADL ファイルにリストされている最後のタグのみが使用されます。現在、1 つのプライマリタグのみがサポートされます。

  • <apigee:tags>

    <tags> 要素は WADL 仕様の Apigee 拡張です。<tags> 要素には、Console のメソッドリストの整理に使用される情報が含まれます。現在のリリースでは、各メソッドに必須の <tags> 要素を含める必要があります。さらに各 <tags> 要素には、1 つの <tag> 要素を含めて、そのプライマリ属性を true に設定する必要があります。例:

    <apigee:tags>
        <apigee:tag primary="true">Timeline</apigee:tag>
    </apigee:tags>

    Console では、プライマリタグはメソッドのカテゴリとして使用されます。この例では、上記の <tag> 要素のメソッドは、Console の「Timeline」カテゴリの下に表示されます。

    apigee:tags

  • <apigee:authentication>

    <apigee:authentication> 要素には 1 つの属性 required が含まれており、認証がこのメソッドに必要であるかどうかの指定に使用されます。例:

    <apigee:authentication required="false" />

    required 属性が true である場合、ロックの記号が Console のメソッドリストに表示され、このメソッドの呼び出しが API プロバイダによって認証されることが示されます。次の例では、最初のメソッドは WADL ファイルで <apigee:authentication required="false"/> として宣言され、2 番目のメソッドは <apigee:authentication required="true"/> として宣言されます。

    メソッド認証タイトル

また各 <method> 要素には、省略可能な <doc> および <request> 子要素を含めることができます。

<doc> 要素

<method> 定義の <doc> 要素は省略可能ですが、推奨されています。指定する場合、<doc> 要素は <request> 要素よりも前に指定する必要があります。<doc> 要素の内容は、メソッドリストでポップオーバーのツールチップとして表示されます。省略可能な apigee:url 属性には、このメソッドのためにホストされているドキュメントへの URL ポインタを指定します。URL は、詳細情報へのリンクとして Console に表示されます。

例えば、WADL のエントリを次に示します。

<doc apigee:url="http://dev.twitter.com/doc/get/statuses/public_timeline">
    存在している場合は、保護されていないユーザーからのリツイートを含めて、最近の 20 件のステータスが返されます。
</doc>

Console UI でマウスポインタ上にツールチップを生成します。

メソッドのドキュメント

<request> 要素

1 つの <request> 要素を <method> 要素に任意に含めることができます。

属性

なし

子要素

Name 説明
<param> メソッドに渡される省略可能な要素。 
<representation> メディアタイプと、リクエストの本文で渡されるペイロードを指定します。

<request>
    <param name="message" required="false" type="xsd:string" style="query" default="">
        <doc>Photo description</doc>
    </param>
    <representation mediaType="application/json">
        <apigee:payload required="true">
            <apigee:content>
            <doc apigee:url="http://api.mydomain.com/doc/resource/method">
                   内容の説明。
            </doc>
                   <![CDATA[{ 
                       "type": "all_day",
                       "timeZone": "-08:00",
                       "timeZoneId": "America/Los_Angeles",
                        ...
                    }]]>
            </apigee:content>
        </apigee:payload>
    </representation>
</request>

説明

<method> 要素には、1 つの <request> 要素を任意に含めることができます。

<request> 要素には、次の要素を含めることができます。
  • メソッドに渡される省略可能な 1 つ以上の <param> 要素
  • 1 つ以上の省略可能な <representation> 要素。複数の <representation> 要素を指定できますが、Console は WADL に定義された最初の <representation> 要素のみを処理します。

次の 3 つの形式で <representation> を指定できます。

  • 本文のパラメータ: フォームエンコードのパラメータとして送信される名前/値のペア
  • ペイロード: XML、JSON などの形式で指定した構造化ペイロード
  • 添付ファイル: 添付ファイルをエンコードする MIME メッセージ

3 つの全 タイプ が 1 つの <representation> 要素に含まれている場合、これらはマルチパート MIME リクエストを構成します。

本文パラメータでの表記

<representation> 要素の本文パラメータは Console の本文タブに表示され、フォームエンコードのパラメータとしてリクエストに渡されます。

<representation mediaType="application/x-www-form-urlencoded">
    <param name="param2" required="true" type="xsd:string" style="query" default="12345">
    <doc>
       パラメータの説明
    </doc>
    </param>
</representation>

Console では mediaType は使用されませんが、読みやすくするために推奨されていします。

ペイロードでの表記

<payload> の内容は Console の本文タブに表示されます。ペイロードはリクエストの本文として渡されます。

例えば、<payload> 要素は、リクエストの本文として JSON ペイロードを送信するために使用できます。例:

<request>
    <representation mediaType="application/json"> 
        <apigee:payload required="true">
           <doc apigee:url="http://api.mydomain.com/doc/resource/method">
               内容の説明。
           </doc>
           <apigee:content>
                <![CDATA[{ 
                    "type": "all_day", 
                    "timeZone": "-08:00",
                    "timeZoneId": "America/Los_Angeles",
                     ...            
                }]]>
           </apigee:content>
        </apigee:payload>
    </representation>
</request>

添付ファイルでの表記

<attachment> 要素を使用すると、添付ファイル UI に情報を事前に入力することができます。<attachment> の内容は、リクエストの本文として渡されます。例えば、<attachment> 要素は、リクエスト内のイメージファイルを送信するために使用できます。 

現在、Console はリクエストあたり 1 つの添付ファイルのみをサポートします。  

必須の name 属性は、MIME パート名とともに Console に入力される名前を決定します。添付ファイルが必須であることを示すには、省略可能な required 属性を使用します。省略可能な contentDisposition 属性は、Console で生成される MIME リクエスト内で Content-Disposition ヘッダーを設定します。

<request>
     <representation>
         <apigee:attachments>
             <apigee:attachment name="image" required="true" contentDisposition="form-data">
             <doc>添付ファイルの説明</doc>
             </apigee:attachment>
         </apigee:attachments>
     </representation>
</request>

<apigee:choice> 要素

省略可能。<resource> 要素には、<apigee:choice> 要素を 0 以上含めることができます。

属性

Name 説明
countMin パラメータの選択肢の最小数を指定します。
countMax パラメータの選択肢の最大数を指定します。
required パラメータの選択肢が必須 (true) であるか、省略可能 (false) であるかを示します。デフォルトは false です。 

子要素

Name 説明
<param> パラメータの選択肢を指定します。

<apigee:choice countMin="1" countMax="1" required="true">
    <param name="user_id_a" type="xsd:string" >
        <doc>
            関係を確認するための元となるユーザーの user_id。
        </doc>
    </param>
    <param name="screen_name_a" type="xsd:string" >
        <doc>
            関係を確認するための元となるユーザーの screen_name。
        </doc>
    </param>
</apigee:choice>

説明

省略可能な <apigee:choice>要素は、<param> 要素の選択肢を指定するために使用できます。この要素には、ユーザーが選択できる選択肢の最小数と最大数を指定する countMin および countMax属性を含めることができます。また <apigee:choice> 要素には、パラメータの選択肢が必須であるかどうかを指定する required 属性を含めることができます。

多くの場合、<apigee:choice> 要素は、2 つの代替的な識別子を選択肢としてユーザーに提示するために使用します。例えば、一部の API メソッドでは、リクエストに含めるためにユーザー ID、画面名 (両方ではない) など、識別子が必要になります。

Apigee WADL 拡張の概要

Apigee Console での表示をサポートするために、基本的な WADL 表記に次の Apigee 固有の拡張が追加されています。

拡張機能 説明
<apigee:authentication> 必須。各 <method> 要素に 1 つ。このメソッドに対して認証が必要であるかどうかを指定します。
<apigee:choice> 省略可能。<resource>要素に含めることができます。この <resource> 要素のために <param> 要素の選択肢を指定します。
<apigee:displayName> 省略可能。<method>要素に含めないか、1 つを含めることができます。Apigee Console に表示するメソッド名を指定します。
<apigee:payload> 省略可能。<request> 要素に含めることができます。<payload> 要素の内容はリクエストの本文で送信されます。
<apigee:tag> 必須。各 <apigee:tags> 要素に 1 つ。メソッドのプライマリカテゴリの指定に使用します。現在 Console では、属性 primary="true" が必須になっています。これは、primary として識別される 1 つのタグが、メソッドをグループ化するためのカテゴリ定義に使用されることを表しています。
<apigee:tags> 必須。各 <method> 要素に 1 つ。Apigee Console 内のメソッドリストの整理に使用します。
<apigee:url> 省略可能。<doc> 要素に含めないか、1 つを含めることができます。その他のドキュメントへの URL リンクを指定します。
<apigee:attachments> 省略可能。<request> 要素に含めることができます。<attachments> の内容はリクエストの本文で送信されます。

留意事項

WADL の作成時に生じる一般的なエラーの 1 つに、特殊文字アンパサンド ( & ) のエスケープを忘れるという問題があります。この文字は、コメントまたは CDATA セクションで使用する場合を除いて、WADL 表記のリテラルフォームでは使用できません。WADL ファイルで任意の場所に & 文字を含める必要がある場合は、エスケープシーケンス &amp; を使用する必要があります。例えば、メソッドに表示名 Users & Apps を指定する場合、次の構文を使用します。

<method id="myMethod" name="GET" apigee:displayName="Users &amp; Apps">

WADL で特殊な意味を持つその他の文字でも、エスケープが同様に必要になります。例えば、かぎ括弧 (< と >) には &lt;&gt; を使用します。

Help or comments?