Was this helpful?

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.

If you are just getting started designing your web API, check out Web API Design, a free eBook by Brian Mulloy, and APIs: A Strategy Guide for some great design considerations.

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.

Comments

Hi,

I am currently working on some WADLs to be uploaded to create a console for our APIs. I would like to know if there is a rest service which is exposed by APIGEE to do this instead of uploading it through APIGEE portal.

Thanks.

Regards,
Monis

Thanks for visiting Apigee docs. We do have a REST interface to upload a WADL but it is unsupported and undocumented. That said it is not public yet. However, if you have a specific requirement to use the REST API, please contact dkinnerkar@apigee.com with complete details.

try and license back .. from instagram URL to access hopefully can land here either static .. just build a new foundation to be able to go in and play with the system here .. I tried to apigee can hopefully permit

thx

thx

Do you have any user/developer facing documentation or tutorials that we could use to teach people how to use the console to go product. We'd like to include it in our Getting Started and Training documentation and would love to leverage anything that you or others may have already created and can share.

Thanks,
Scott Gilbert

Hey Scott - Thanks so much for the post. You know, we don't currently have any end user docs on using the console-to-go, but we've now got it on our radar. Possibly a video. We've also got some new API documentation features on our product radar. Either way, we'll try to meet this need fairly soon. Cheers, Floyd

We currently have our own API Console but we are considering using ApiGee instead.

Question: is it possible the configure the console to fetch its WADL.xml from another location dynamically, alternatively to upload it via an API? Updating the actual WADL would be handled in the developers' repositories, and when we deploy new code to production we could automate the update of WADL in the ApiGee console.

Just now saw that you've received a question similar to this. Oh well, now you know of a perceived need from our part as well :)

Hi Jon,

To make a feature request, please contact dkinnerkar@apigee.com with complete details.

Thanks,

Stephen

Thanks for that, Jon. Also, stay tuned for an upcoming feature that's an alternative to console. You'll be able to generate API docs with an API call. Release date TBD.

We are using the console to self document our custom API. We are embedding it on an internal site so our users have access to it after logging in to our site. Is there a way to pass URL variables to the console-to-go so we can populate their custom authentication information when the console starts?

Hi Rory,

There is a way to pass in an auth token with the iframe's embed URL, with the value of the "auth" query parameter as a URI-encoded snippet of JSON like:

?auth=%5B%7B%22type%22%3A%22custom_token%22%2C%22name%22%3A%22key%22%2C%22value%22%3A%22some_key%22%2C%22style%22%3A%22template%22%7D%5D

Which, un-encoded, looks like:

[{"type":"custom_token","name":"key","value":"some_key","style":"header"}]

And that allows the parent page of the embedded Console to pre-set the auth. The other supported styles are "query" and "template".

I'm having issues trying to implement OAuth 2 as an option for Authentication for our API Console To Go. There doesn't seem to be any explanation of the flow, is there any documentation or tutorial I can follow?

To elaborate, under OAUth 2.0 Web Server Flow, I'm not sure what you mean by "Access Token Location". Our OAuth URL returns the access_token in the JSON response to the POST to our access_token URL.

Hi Matthew,

The "Access Token Location" is to specify whether the 'access_token' should be sent as header or query parameter in the API Call.

For e.g., if the target server expects the request to be http://api.mydomain.com/test?access_token=, then the 'Access_Token_Location' should be 'Query Parameter' and the 'Access Token Param Name' should be 'access_token'.

Hope this answers your question. Let us know if you have any other concerns.

Does the WADL can describe the oauth urls? like the get access token url?

Original reply from Marsh:
Michale, no, there is no apigee:element for declaring the authentication configuration. If you have any suggestions, we'd love to hear them. (This is something we've considered in the past.)

Hi Michale,
You can describe the OAuth URL in the WADL like any other API description. It will show up in the Method list along with the other APIs.

Thanks,
Deepti

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.