By creating and deploying API proxies, you are bringing new APIs into the world. Every API proxy that is deployed in an environment exposes an API. The API may be a facade for existing services, or it may simply expose a JavaScript or Node.js application.

You need to provide developers with a way to discover, understand, and consume these APIs. You can do this by creating a file that describes your API in a commonly-understood way. There a few different languages available for service description. For API, you commonly use the web application description language (WADL).

For a more detailed information about WADL, see the WADL specification on the World Wide Web Consortium (W3C) website at http://www.w3.org/Submission/wadl/.

WADL is a specification (not a standard) for codifying the structure of an interface that is both human and machine readable. There is naturally much debate about the best solution for describing APIs. Apigee treats WADL as a useful (though limited) tool for describing interfaces, but makes no broader claims on WADL's behalf.

Many tools are available for generating WADL files from your application code. WADL files can reasonably be constructed by hand. WADL files are XML files and typically use the .xml extension.

Use a single WADL file to describe all of your APIs. Once you have a WADL file you can publish it to developers by using the Apigee API Console To-Go. To do so, upload the file to Apigee using the web form at the Console To-Go web page. Like modeling an API, creating a Console is an iterative process. You can then customize the look and feel of the custom Console. Once you are satisfied with your custom Console is created, you deploy it either to your own web site or to your Developer Services portal.

What is WADL?

The Web Application Description Language (WADL) is an XML-based file format that provides a machine-readable description of HTTP-based web APIs. A WADL file defines the resources (that is, URIs) that constitute an API. For each resource, WADL defines one or more  methods that act on those resources. With RESTful APIs, a method is a combination of a resource (URI)  and the HTTP verb (most commonly GET, PUT, POST and DELETE) that acts on the resource. WADL in its simplest form defines create, read, update and delete actions (sometimes referred to as CRUD operations) on resources defined by the API.

For example, an API that defines 3 resources: articles, comments, and users.

  • http://api.example.com/v1/articles
  • http://api.example.com/v1/comments
  • http://api.example.com/v1/users

For each API resource, developers need a way to create, to read, to update, and to delete the resource--in other words, a set of methods is required for each resource.

RESTful APIs usually define a:

  • POST method (for creating an article)
  • PUT method (for modifying an existing article)
  • GET method (for retrieving the article)
  • DELETE method (for removing articles)

Methods can in turn have parameters. Parameters provide additional granularity over interactions with resources. There are a number of different ways of working with parameters in WADL. Usually, a parameter takes the form of a query parameter, as in this example:

  • http://api.example.com/v1/articles?topic=programming

One benefit of using the Apigee Console is that it enables developers to quickly understand which parameters are supported by your API, and how developers can use parameters to accomplish specific tasks.

Let's define a WADL for one resource and one method of this API. The WADL below defines:

  • The base path for the API
  • A single resource defined by the /articles URI path
  • A single GET method on the /article resource. The method returns a list of all articles.
  • A single query parameter on the GET method, topic, which enables filtering all articles by topic.
<resources base="http://api.example.com/v1">
    <resource path="articles">
        <method id="listArticles" name="GET">
             <request>
                 <param name="topic" required="true" 
                     type="xsd:string" style="query" default=""/>
             </request>
        </method>
     </resource>
</resources>

Now let's turn the WADL above into a WADL that the Apigee Console can display,including wrapping it in an <application> tag and written to the file myExampleWADL.xml:

<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/v1">
        <resource path="articles">       
            <method id="listArticles" name="GET" apigee:displayName="List Articles">
                <apigee:tags>
                    <apigee:tag primary="true">Articles</apigee:tag>
                </apigee:tags>
                <apigee:authentication required="true"/>
                <doc apigee:url="http://doc.example.com/apis/listArticles.html">
                    Use the GET method to list all articles, filtered by 'topic'
                </doc>
                <request>
                   <param name="topic" required="true" 
                       type="xsd:string" style="query" default=""/>
                </request>
            </method>
        </resource>
    </resources>
</application>

How does Apigee extend the WADL standard?

Apigee extends the base WADL specification with Apigee-specific elements. These extensions enable you to control how your API is displayed in the Console, and also enables you to enrich the Console with additional documentation about your API.

Apigee defines WADL extensions for the following:

  • Authentication: The <apigee:authentication> tag indicates whether an API method required authentication
  • Tag: The <apigee:tags> and <apigee:tags> tags specify an identifier on an API method that enables the Console to group related API methods into categories
  • Choice: The <apigee:choice> tag enables you to define a set of parameters that the Console presents to the user for selection
  • Display Name: The apigee:displayName  attribute to the <method> tag specifies a user-friendly name for an API method that the Console displays to the user
  • Payload: The <apigee:payload> child tag of a <request> tag specifies a JSON or XML request body (often used with POST or PUT operations) that displays to the user in the Console and that is submitted to your API as part of the request message
  • Attachments: The <apigee:attachments> child tag of a <request> tag enables the Console user to select a file (an image, a sound file, a video file) to be included as a MIME encoded attachment to the request message
  • Doc URL: The apigee:url attribute of the <doc> tag specifies a link to a Web page, hosted by you, the API provider,  that provides more information about an API method

Only two of these extensions are required: authentication and tags. For your WADL to work in the Console, you must add authentication and tags elements to all of the API methods defined in your WADL. The remainder of these extensions are optional, and they can be used where necessary to improve the user experience of your API for the Console user.

The Apigee-specific tags are prefixed with the keyname apigee, as in <apigee:tags> and <apigee:authentication>.

(See Summary of Apigee WADL Extensions in WADL Reference for a complete list of the Apigee-specific WADL extensions.)

Creating a WADL for the Apigee Console

There are two strategies for creating a WADL for use in the Apigee Console:

Strategy 1: Download the sample WADL file provided by Apigee. Use it as a starting point for describing your API. Create WADL entries for one or two of your API methods. Upload to the Apigee Console. Once those methods work to your satisfaction, and then incrementally add the remaining API methods to the WADL file. Download a sample WADL here, or use the link on the right side of the Apigee Console To-Go web page. For even more specificity, you can refer to the Apigee WADL Schema here

Strategy 2: Use a tool, such as the open source Jersey automatic XML schema generator, to create a WADL. Add the required Apigee WADL extensions, authentication and tags, to your WADL for it work in the Console. Other extensions, such as documentation URL, are optional, and can be added at your discretion. 

WADL Reference walks through the WADL representation, and WADL Elements in that article shows how the various elements are displayed in the Apigee Console. Summary of Apigee WADL Extensions in WADL Reference summarizes the Apigee-specific extensions.

Creating an Apigee Console To-Go and uploading a WADL file

To create an Apigee Console To-Go, you must have an account on https://enterprise.apigee.com. While any developer can create a Console To-Go, you typically create a single console for your portal.

A Console To-Go does not enforce any access restrictions. That means anyone can see a Console To-Go created by anyone else. However, you can apply access credentials to your APIs. In that way, while anyone can see your console, only users with the necessary credentials can make requests to them.

The Console To-Go creation process is defined by three steps:

  1. Set Up - The only required step. In this step, you specify the name and URL of the Console To-Go, specify the credentials required to access your APIs, and upload your WADL file.
  2. Style - (Optional) Set styles to control the appearance of your Console To-Go.
  3. Embed - (Optional) Copy the <iframe> tag that lets you embed your Console To-Go on another page.

Steps 2 and 3 are optional. You only have to perform step 1 to create your Console To-Go and upload a WADL file. You can optionally perform steps 2 and 3 when you create the Console To-Go, or come back and perform those steps later. 

To set up a console and upload a WADL file:

  1. Login to your Apigee account at https://enterprise.apigee.com. (You can obtain a free account at https://accounts.apigee.com/accounts/sign_up.)
  2. Open the following URL: https://apigee.com/togo. The Console-To-Go page opens to step 1 - Set up:
  3. Specify the Name of your Console and the URL.
  4. Save your console.
  5. Scroll down the page and select the credentials required to access your Console To-Go.
  6. Select Save Credentials.
  7. Scroll down the page to upload your WADL file.
  8. Select the Browse button, navigate to your WADL file, and select Open.
  9. Select the Upload button.
    If the Console To-Go detects any errors in your WADL file, it displays an error message.
  10. Repeat steps 8 and 9 to update the WADL file. All of your APIs must be described in a single WADL file.
    You can upload an initial WADL file when you create the Console To-Go, and then return to https://apigee.com/togo at anytime to update the WADL file.

To style a console:

  1. Ensure that you have already created a Console To-Go as described above.
  2. Open the following URL: https://apigee.com/togo.
  3. Specify the name and URL of your existing console.
  4. Select 2. Style at the top of the page.
  5. Edit the styles for your Console To-Go and select Save Changes.

To embed your console on a separate page:

  1. Ensure that you have already created a Console To-Go as described above.
  2. Open the following URL: https://apigee.com/togo.
  3. Specify the name and URL of your existing console.
  4. Select 3. Embed at the top of the page.
  5. Copy the <iframe> tag from the page to the destination page.

Deploying your Apigee API Console To-Go

After you create your Apigee API Console and uploaded your WADL files, you have several options for deployment:

Option 1:  Embed the custom Console that you create on your own web site or  developer portal. As part of the Apigee API Console creation process, Apigee generates an HTML iframe tag that enables you to embed your Console. The <iframe> tag renders the Console on the web page where it is embedded.

Option 2: Distribute the URL to your console so developers can access it directly. For example, you can add a link to the top-level menu bar on your portal to the console.

Option 3: Have your Console included on the Apigee providers page. This no-cost option increases visibility for your API, and it can attract new developers to your API. Contact Apigee at consoles@apigee.com for more information on listing your Console on the Apigee site.

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