Access Yahoo's Place Finder Search Using an API

Introduction

This sample demonstrates how to subscribe to a published API and consume its functionality using the API Store Web application. The API used here provides place-finder search functionality of Yahoo.

Prerequisites

1. Execute the steps in Samples Setup. When you are done, you will have the API Manager started and the relevant scripts run to create user accounts for API Publisher and API Store.

Building the Sample

1. First, we need to add an API in the API Publisher and publish it to the API Store. To do that, simply run the APIPopulator.sh (for Linux) or APIPopulator.bat (for Windows) files from folder, <AM_HOME>/samples/YahooPlaceFinder.

2. The script will add an API to the API Publisher in 'Published' state. This API can then be consumed by any user signed in to the API Store.

Executing the Sample

Subscribing to the API

1. Log in to the API Store (https://localhost:9443/store) with credentials subscriber1/subscriber1.

2. Click the "APIs" tab at the top of the page and select the "YahooPlaceFinder" API.

3. Next, subscribe to this API. Simply select the default application and throttling tier as "Bronze" as shown below.

4. You will be asked to navigate to "My Subscriptions" tab. Accept it.

5. Next, you can generate a key to the application. Click on the "Generate" option in the box titled "Production" to obtain an Application key. For example,

Invoking the API

6. Once you have obtained a key, you can invoke the API using a REST client of your choice. In this example, we use cURL (http://curl.haxx.se).

7. Copy and paste following into a new console window and execute it.

curl -v -H "Authorization: Bearer 9nEQnijLZ0Gi0gZ6a3pZICktVUca" http://localhost:8280/placeFinder/1.0.0?q=Colombo

where, API key = 9nEQnijLZ0Gi0gZ6a3pZICktVUca. Replace this value with the API key you generated through the API Store in step 5 above.

The <API Key> is passed in the Authorization header as a value of "Bearer". The Authorization header of the message is prefixed by the string "Bearer". This is because, WSO2 API Manager enforces OAuth security on all the published APIs. Any consumer that talks to the API Manager should send their credential (application key) as per the OAuth bearer token profile. If you don't send an application key or send a wrong key, you will receive a 401 Unauthorized response in return.

8. You should be able to see search results from Yahoo's Place Finder on your console. For example,

<ResultSet version="1.0">
   <Error>0</Error>
   <ErrorMessage>No error</ErrorMessage>
   <Locale>us_US</Locale>
   <Quality>40</Quality>
   <Found>1</Found>
   <Result>
      <quality>40</quality>
      <latitude>6.927200</latitude>
      <longitude>79.872200</longitude>
      <offsetlat>6.927200</offsetlat>
      <offsetlon>79.872200</offsetlon>
      <radius>6500</radius>
      <name /><line1 />
      <line2>Colombo</line2>
      <line3 />
      <line4>Sri Lanka</line4>
      <house /> <street /><xstreet /><unittype /><unit /><postal /><neighborhood />
      <city>Colombo</city>
      <county>Colombo</county>
      <state>Western</state>
      <country>Sri Lanka</country>
      <countrycode>LK</countrycode>
      <statecode /><countycode /><uzip /><hash />
      <woeid>2189783</woeid>
      <woetype>7</woetype>
   </Result>
</ResultSet>

9. Executing the above command several times with different API keys. Note the authentication failures returned by the API Gateway when you pass invalid API keys. After a few invocations, the throttling policy of the API will get activated and the API Gateway will start responding with 503 Service Unavailable response messages.