The basic outline format of an example WADL representation is shown below. A WADL representation first defines a <resources> element, which identifies the base path of all resources in the API. Then it defines one or more <resource> elements, each of which describes a resource in the API. Each <resource> element definition includes the methods, parameters, and associated documentation for the resource.

The following excerpt of an example WADL representation includes a single <resources> element, defining a single base path endpoint for the API. Next, a <resource> element is defined within the <resources> element. This <resource> element contains one or more <method> definitions that define the actions available for this API resource. In a typical WADL representation, multiple <resource> elements would follow, one for each resource in the API.

<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 elements

The following sections provide reference information for each WADL element. The information includes:

  • Whether the element is required or optional.
  • How many instances of the element must or can be specified.
  • The name and description of the element's attributes and child elements.
  • An example of the element.
  • A description of the element.

The <resources> element

Required. One or more <resources> elements are required for each WADL specification.

Attributes

Name Description
base Base path of the endpoint

Child elements

Name Description
<resource> Describes the API resource

Example

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

Description

Each WADL specification contains at least one <resources> element. The <resources> element contains one attribute, base, that defines the domain and the base path of the endpoint. Each <resources> element usually contains multiple <resource> elements.

If an API has more than one endpoint, you need to include one <resources> element for each endpoint; within each <resources> element, you'll put the <resource> elements that fit under that base URL. For example, your API may have one endpoint at http://api.example.com/search/v1 and another at http:api.example.com/community/v1. The WADL representation for this API would include two <resources> elements, each with the corresponding base URL.

The <resource> element

Required. One or more <resource> elements are required in each <resources> element.

Attributes

Name Description
path Path to the resource

Child elements

Name Description
<param> Specifies parameters used for requests to this resource
<apigee:choice> Specifies a choice of <param> elements
<method> Defines a method associated with this resource
<resource path="statuses/public_timeline.{format}">
    <param> ... </param>
    <param> ... </param>
    <method> ... </method>
</resource>

Description

Each resource in your API is described by a <resource> element in the WADL file. A <resource> element has a path attribute that specifies the path to that resource. The value of the path attribute can be static, or it can contain embedded template parameters (such as {format} in the example above).

The complete path name of the resource is generated by concatenating the value of the base attribute in the <resources> element and the value of the path attribute in the <resource> element. In addition, any template parameters, such as {format} in this example, are replaced with the values that are entered by the user in the Console (or their default value, if one is defined). In this example, the complete path name for this resource is:

Each <resource> element can contain zero or more optional <param> elements that define parameters. If included, these parameters are used by methods defined as part of this <resource> element. A <resource> element can also include optional <apigee:choice> elements, which define a set of parameter choices. (See The <apigee:choice> element for more information.)

Note: If a <resource> element contains <param> elements, they must appear in the WADL representation before the <method> element. Listing the <param> elements after the <method> element generates an error when uploading your WADL to Apigee. Alternatively, the <param> elements can be included in the <method> element declaration as part of a <request> element. In the former approach, all of the methods inherit the <param> elements. In contrast, if you include the <param> elements within the method, the parameter is limited to the scope of that method.

Each resource typically contains one <method> element. However, resources that share the same path but have multiple verbs can have multiple <method> elements in the WADL representation. For example, a single resource may have both a GET and a POST method. In this case, there could be a single <resource> definition that includes two <method> definitions, one for each verb.

The <param> element

Optional. Zero or more <param> elements can be included in a <resource> or <request> element.

Attributes

Name Description
name The parameter name
required Indicates whether the parameter is required (true) or optional (false).  The default is false.
type The expected XML Schema data type of the parameter (for example, "xsd:string")
style The expected type of parameter (for example, "query" or "header")
default The default  value for the parameter

Child elements

Name Description
<doc> A text description of the parameter
<option> The possible set of values for the parameter

Example

<param name="count" required="false" type="xsd:string" default="5">
    <doc>Specifies the number of records to retrieve.
          Must be less than or equal to 200.</doc>
</param>

Description

Each <resource> element can contain zero or more optional <param> elements that describe parameters used for requests to this resource. Parameters are grouped by type (query, template, headers) on the corresponding tabs in the Console, and are listed in the order they appear in the WADL file.

Note: <param> elements can also be included in a <request> element.

A <param> element contains the following attributes and child elements:

  • name

    The name attribute specifies the parameter name. This value is displayed in the parameter list in the Console. All parameter names for a given method should be unique within the scope (for example, within that method).

  • required

    The required attribute should be set to true if the parameter is required, and false if the parameter is optional. Required parameters are marked in the Console with a red asterisk. Default values can be specified using the default attribute.

    For example, the parameter of name "type" in the following example is required, and has a default value of "text". Both the parameter itself and the Query tab are marked with a red asterisk, indicating that they are required.

    Note: Currently, the Apigee Console allows a user to send a request without a required parameter, so that these requests can intentionally fail. This helps a user find out what errors result under certain conditions. However, the Console displays clearly what the user should do to correct the error.

  • type

    The type attribute specifies the expected type of the parameter. Valid values are any of the predefined set of standard XML Schema data types. Example values include xsd:string, xsd:boolean, and xsd:integer.

  • style

    The style attribute specifies the type of the parameter. Valid values include query, header and template.

    Parameters are displayed under the corresponding tab in the Console UI, and are listed in the order they appear in the WADL.

  • default

    The optional default attribute specifies a default value for this parameter. If a default value is included, it is displayed in the Console when a user selects this resource. If the parameter if required, the default value is automatically entered into the value field for this parameter on the Console.

    If the parameter is optional, the default value is displayed as placeholder text in the Console and is followed by the text "(example)". If the user enters a value for an optional parameter, the grayed-out text is replaced with the value the user choose. The following example shows an optional parameter count with a default value of 200:

  • <doc>

    The <doc> element is optional, but recommended. This element contains plain text documentation that describes this parameter. This documentation is displayed in the Console, associated with the parameter name and value field. An optional apigee:url attribute contains a URL for additional documentation, and this appears as a link to more information in the Console.

    Note: Only plain text is supported for <doc> elements.

    For example, the following entry in a WADL file:

    <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[ The number of results to return: 1-20, inclusive ]]>
        </doc>
    </param>

    generates this Console UI:

    The following <doc> element:

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

    generates this default link to more information in the Console UI:

  • <option>

    A <param> element can also contain <option> elements that enumerate the possible set of values for the parameter. All option values should be unique for a given parameter. For example, the following query-style parameter has several options defined:

    <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>

    If the WADL representation contains options for a given parameter, those options are displayed in the Console as a drop-down menu. If the parameter is not required, the drop-down menu also includes the option (blank) for cases when the user wishes to omit the parameter. Options are listed in the menu in the order they appear in the WADL file. For example:

The <method> element

Required. One or more <method> elements are required in each <resource> element.

Attributes

Name Description
id The unique identifier for this method
name The type of HTTP method used (GET, POST, DELETE, or PUT)
apigee:displayName The display name for the method in the Apigee Console

Child elements

Name Description
<apigee:tags> Used to organize the methods in the Apigee Console
<apigee:authentication> Specifies whether authentication is required
<doc> Specifies tooltip text to be displayed when the user mouses over the method in the Apigee Console
<request> Specifies one or more <param> elements that are passed to the method.

Example

<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>

Description

The <method> element is associated with an individual method in the API, and is described by an id and name attribute. Each <method> element in a WADL representation must have a unique ID. The name attribute specifies the type of HTTP method used, either GET, POST, DELETE, or PUT.

Each <method> element also includes an optional display name, specified by the apigee:displayName attribute. The display name contains the text that is displayed in the method list in the Console. If no display name is specified, the <resource> element's path attribute is displayed in the Console as the name of the method.

Each method also includes the following Apigee extensions to the standard WADL: <apigee:tags> and <apigee:authentication>. These Apigee extensions are required for each method declaration. In addition, these extensions must be included in the WADL in this exact order: <apigee:tags> <apigee:authentication>.

Tags enable methods to be organized into groups. In the Console, methods are grouped within the tags you define, making them easier to navigate. As such, tags function as categories for methods. Tags are displayed within the Console in alphabetical order. The methods organized under a tag appear in the order in which they are defined in the WADL.

Note: If no tag element contains a primary attribute set to "true", then the method does not appear in the list of methods in the Console. Also, if more than one tag element contains a primary attribute set to "true", then only the last tag listed in the WADL file is used. Currently, only a single primary tag is supported.

  • <apigee:tags>

    The <tags> element is an Apigee extension to the WADL specification. The <tags> element contains information used to organize the list of methods in the Console. In the current release, each method must include a required <tags> element. Furthermore, each <tags> element must contain one <tag> element with the primary attribute set to "true". For example:

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

    In the Console, the primary tag is used as the category for the method. In this example, a method with the above <tag> element is displayed in the Console under the "Timeline" category:

  • <apigee:authentication>

    The <apigee:authentication> element contains a single attribute, required, that is used to specify whether authentication is required for this method. For example:

    <apigee:authentication required="false" />

    If required attribute is  "true", a lock symbol displays in the Console method list, indicating that invocations of this method are authenticated by the API provider. In the following example, the first method is declared in the WADL file as <apigee:authentication required="false"/>, and the second method is declared as <apigee:authentication required="true"/>.

Each <method> element can also contain optional <doc> and <request> child elements:

  • <doc>

    The <doc> element in a <method> definition is optional, but recommended. The contents of the <doc> element display as a popover tool tip in the method list. The optional apigee:url attribute contains a URL pointer to hosted documentation for this method. The URL displays as a link to more information in the Console.

  • For example, the following entry in WADL:

    <doc apigee:url="http://dev.twitter.com/doc/get/statuses/public_timeline">
        Returns the 20 most recent statuses, including retweets if they exist, from non-protected users.
    </doc>

    generates a tool tip on mouse over in the Console UI:

The <request> element

Optional. One <request> element can be included in a <method> element.

Attributes

None

Child elements

Name Description
<param> Optional elements that are passed to the method. 
<representation> Specifies the media type and payload passed in the body of the request

Example

<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">
                   Content description.
            </doc>
                   <![CDATA[{ 
                       "type": "all_day",
                       "timeZone": "-08:00",
                       "timeZoneId": "America/Los_Angeles",
                        ...
                    }]]>
            </apigee:content>
        </apigee:payload>
    </representation>
</request>

Description

A <method> element can optionally contain one <request> element.

A <request> element can contain:
  • One or more optional <param> elements that are passed to the method.
  • One or more optional <representation> elements. (While you can specify more than one <representation> element, the Console only processes the first <representation> element defined in the WADL.)
The <representation> can take  three forms:
  • Body parameters: Name/value pairs sent as form-encoded parameters
  • A payload: A structured payload formatted in XML, JSON, etc.
  • An attachment: A MIME message that encodes an attached file

All three types in a single <representation> element constitute a multipart MIME request.

Body Parameter Representation

Body parameters of the <representation> element are displayed in the body tab of the Console and are passed as form-encoded parameters to the request.

<representation mediaType="application/x-www-form-urlencoded">
    <param name="param2" required="true" type="xsd:string" style="query" default="12345">
    <doc>
       Parameter description.
    </doc>
    </param>
</representation>

The Console does not consume the mediaType, but it is recommended for readability.

Payload Representation

The contents of the <payload> are displayed in the body tab of the Console. The payload is passed as the body of the request.

A <payload> element can, for example, be used to send a JSON payload as the body in the request. For example:

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

Attachment Representation

The <attachment> element enables you to pre-fill information in the attchment UI. The contents of the <attachment> are passed as the body of the request. An <attachment> element can, for example, be used to submit an image file in the request. 

Currently, the Console only supports a single attachment per request.  

The name attribute, which is mandatory, determines the name populated in the Console as well as the MIME part name. Use the optional required attribute to indicate that an attachment is mandatory. The optional contentDisposition attribute sets the Content-Disposition header in the MIME request generated by the Console.

<request>
     <representation>
         <apigee:attachments>
             <apigee:attachment name="image" required="true" contentDisposition="form-data">
             <doc>Attachment description.</doc>
             </apigee:attachment>
         </apigee:attachments>
     </representation>
</request>

The <apigee:choice> element

Optional. Zero or more <apigee:choice> elements can be included in a <resource>element.

Attributes

Name Description
countMin Specifies the minimum number of parameter choices
countMax Specifies the maximum number of parameter choices
required Indicates whether the parameter choice is required (true) or optional (false).  The default is false. 

Child elements

Name Description
<param> Specifies a parameter choice.

Example

<apigee:choice countMin="1" countMax="1" required="true">
    <param name="user_id_a" type="xsd:string" >
        <doc>
            The user_id of the user you are checking the relationship from.
        </doc>
    </param>
    <param name="screen_name_a" type="xsd:string" >
        <doc>
            The screen_name of the user you are checking the relationship from.
        </doc>
    </param>
</apigee:choice>

Description

The optional <apigee:choice> element can be used to specify a choice of <param> elements. This element can contain countMin and countMax attributes that specify the minimum and maximum number of choices, respectively, a user can select. The <apigee:choice> element can also contain a required attribute, that specifies whether a parameter choice is required.

The <apigee:choice> element is often used to present the user with a choice of two alternative identifiers. For example, some API methods require an identifier, such as either a user ID or screen name (but not both), to be included in a request.

Summary of Apigee WADL extensions

The following Apigee-specific extensions have been added to the base WADL representation to support display in the Apigee Console.

Extension Description
<apigee:authentication> Required; one in each <method> element. Specifies whether authentication is required for this method.
<apigee:choice> Optional; can be included in a <resource> element. Specifies a choice of <param> elements for this <resource> element.
<apigee:displayName> Optional; <method> elements can contain zero or one. Specifies the method name to display in the Apigee Console.
<apigee:payload> Optional; can be included in a <request> element. The contents of the <payload> element are sent in the body of the request.
<apigee:tag> Required; one in each <apigee:tags> element. Used to specify the primary category for a method.The attribute primary="true" is currently required by the Console--meaning that the single tag identified as primary is used to define the category in which the method will be grouped.
<apigee:tags> Required; one in each <method> element. Used to organize the list of methods in the Apigee Console
<apigee:url> Optional; <doc> elements can contain zero or one. Specifies a URL link to additional documentation.
<apigee:attachments> Optional; can be included in a <request> element. The contents of the <attachments> are sent in the body of the request.

Gotchas

One common error in creating a WADL is forgetting to escape the special ampersand character ( & ). This character cannot occur in its literal form in a WADL representation, except when it's used within a comment or in a CDATA section. If you need to include the & character anywhere else in the WADL file, you need to use the escape sequence &amp;. For example, if you want your method to have the display name "Users & Apps," use the following syntax:

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

Other characters that have special meaning in the WADL similarly need to be escaped. For example, use &lt; and &gt;, respectively, for angle brackets (< and >).

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)