Set up an Apigee API Console

Was this helpful?

This document assumes you have already designed a web API. 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.

To generate an interactive Console for your API, Apigee relies on an application description that you construct to define your API. There are several approaches to describing an API in a structured fashion. The approach that Apigee uses is based on the  Web Application Description Language (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. 

The base requirement for creating a Console for your API is WADL description. Many tools are available for generating WADL files from your application code. WADLs can also reasonably be constructed by hand. The console is agnostic as to how you arrive at your WADL. 

Once you have a WADL file that describes your API,  you import the file to Apigee using the web form at the Console To-Go web page. 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 portal. 

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

Note: The Console To-Go web page walks you through the steps of creating your Apigee API Console.

Back to top

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 reources. 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 refered to as CRUD operations) on resources defined by the API.

Let us take as an 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 resource, developers need a way to create, to read, to update, and to delete each 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/">
    <resource path="articles">
        <param name="baseurl" type="xsd:string" style="template" required="true" default="api.example.com">
            <doc>The top-level domain of the API</doc>
        </param>
        <param name="version" type="xsd:string" style="template" required="true" default="v1">
            <doc>The version of the API</doc>
        </param>

        <method id="listArticles" name="GET">
             <request>
                 <param name="topic" 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:

<resource path="articles">       
             <param name="baseurl" type="xsd:string" style="template" required="true" default="api.example.com">
            <doc>The top-level domain of the API</doc>
        </param>
        <param name="version" type="xsd:string" style="template" required="true" default="v1">
            <doc>The version of the API</doc>
        </param>
        <method id="listArticles" name="GET" apigee:displayName="List Articles">
            <apigee:tags>
                <apigee:tag primary="true">Articles</apigee:tag>
            </apigee:tags>
            <apigee:authentication required="true"/>
            <apigee:example url="organizations/{org_name}/apiproducts"/>
             <doc apigee:url="http://doc.exmaple.com/apis/listArticles.html">
                Use the GET methodto list all articles, filter by 'topic'
             </doc>
             <request>
                 <param name="topic" type="xsd:string" style="query" default=""/>
             </request>
            </method>
      </resource>

Back to top

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: Indicates whether an API method required authentication
  • Tag: An identifier on an API method that enables the Console to group related API methods into categories
  • Choice: Enables you to define a set of parameters that the Console presents to the user for selection
  • Display Name: A user-friendly name for an API method that the Console disaplys to the user
  • Payload: A JSON or XML request body (ofent 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: 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: 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, example are <apigee:tags> and <apigee:authentication>.

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

Back to top

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, incrementally add the remaining API methods. Download a sample WADL here, or use the link on the right side of the Apigee Console To-Go web page. For even more specificty, 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. Two extensions are required (authentication and tags), and those must be added 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.

Back to top

Deploying your Apigee API Console

After you create your Apigee API Console, you have two 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 embedyour Console. The iframe renders the Console on the web page where it is embedded.

Option 2: 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.

Back to top