11436 SSO

Apigee v2 Console: Making learning APIs as simple as possible, but no simpler

mbierman
Feb 28, 2012

The most delightful learning experiences are natural and effortless. With that in mind, we at Apigee strive to minimize the time it takes to make your first successful API request.

We make it as simple as possible to learn how to make successful API calls, but  don’t prevent you from purposefully making failing requests, which can be useful while troubleshooting. Read on!

In the v2 Console, there are three new features that make it simple for you to learn an API.

Contextual Help

Let’s face it, nobody likes documentation until they get stuck and then, only as much as they need to get their work done. For a long time, people have asked us for deep-linked documentation right in the console. API Providers can now add summaries and deep-links to every method and parameter in the Console and API Resource pages.

In many cases, you have all you need to know to make a successful API request right in the Console but if that’s not enough, you can go directly to the full documentation at the API provider’s site.

Parameter Surfacing

Even the best APIs can be complex to learn. We’ve made it even easier to make a successful API request by surfacing all of the parameters in an intuitive way. In most cases, you can choose an API provider (1), select the service (base URI) (2), and method (4) you want to work with and send the request.

You’ll see right away if the method requires authentication (3) or parameters (5) and you can add those as well.

You are alerted if you are missing any of the required parameters as shown below.

All of the parameters defined in the API should automatically be listed in the appropriate query tab including:

Query parameters: In this query the alt parameter is set to ‘atom’.

In this case, the API specifies that this must be one of 5 types and all are shown in a drop-down menu. This would show up in the request as

http://gdata.youtube.com/feeds/api/users/apigee?alt=atom&prettyprint=true&v=2

where alt=atom is a drop down and prettyprint=true is a Boolean value in the Query tab.

You can additionally add any custom name/value pairs to the query of the API request.

Template parameters: are associated with parameters in the URI path. In the example above, {username} is a template parameter and can be provided in the Template tab.

This is a required field as noted by the asterisk. You can additionally add any custom name/value pairs to the query of the API request.

Header parameters: are your chance to modify the headers of the request. user-agent is a very common choice and we’ve provided it for you so, for example, you can simulate sending the request from an iPhone or Android device.

You can additionally add any custom name/value pairs to the Header of the API request.

Body parameters: are typically for an attachment like uploading a video or picture or an XML, or JSON payload.

While we’ve made it easy to make successful API requests, we don’t prevent you from purposefully making failed requests. These are often helpful in isolating problems. As simple as possible, and no simpler!

Bookmarking API Requests

Another new feature of the v2 Console is the ability to bookmark API requests complete with the method and every parameter. This allows you to to repeat a range of test cases or share a particular API query in a blog.

For example, say I wanted to instruct you on the Youtube /feeds/api/users method. I could simply provide a link and it would load the console ready to make the request. Go on, try it.

As you can see, this will give you a list of great Apigee videos in atom format. This can also be used by API providers to make it easy for developers to instantly try examples from their reference documentation, on discussion boards, or email threads.

These are just a few of the great features included in the new v2 Console. With over 60 API providers, there are a lot to choose from.

If you would like a Console for an API that you don’t see, please send an email to consoles@apigee.com. You can use the Generic/Other console which allows you to send any REST request.

 

APIs for Dummies

Next Steps

 
 

Resources Gallery

News