Build a simple proxy for the EveryTrail public API using IBM WebSphere Cast Iron Live Web API Services

To reach new channels of mobile customers, organizations are investing in exposing existing IT assets via web APIs, making their business available instantly on mobile devices. IBM WebSphere® Cast Iron® Live Web API Services is a cloud offering that enables organizations to quickly expose enterprise APIs with an easy-to-use solution. Web and mobile developers can use these web APIs to build rich web and mobile applications. In addition, the Cast Iron Live API facilitates the building of developer portals for those exposed web APIs. This article offers a simple example of how to proxy a publicly available API using IBM's API solution.

Share:

Dinesh G Shetty (dinu.shetty@in.ibm.com), Senior IT Specialist, IBM

Author photoDinesh Shetty is a Senior IT Specialist at the IBM India Software Labs in Bangalore, working in the Software Services for WebSphere organization. He has over 12 years of experience in IBM middleware technologies like WebSphere MQ, Message Broker, and DataPower, and has implemented IT solutions in the areas of connectivity and integration. Dinesh also leads the IBM API Management Community for ISSW and drives consulting and enablement efforts in related areas. Previously, Dinesh worked in the WebSphere Message Broker development lab.



Rakesh Nair (rakesh.nair@in.ibm.com), IT Specialist, IBM

author photo - rakesh nairRakesh Nair is an IT Specialist at the IBM India Software Labs in Bangalore, working in the Software Services for WebSphere organization. He has over 11 years of experience, and has implemented solutions in IBM middleware technologies like DataPower and WESB. He has also implemented IT solutions in the areas of connectivity and integration in the health care, finance, and insurance industries. He also supports sales activity for WebSphere Datapower, and is now assisting with the Web API Management initiative.



05 April 2013

Introduction

Try it!

Sign up for a free, 90-day cloud-hosted trial of Cast Iron Live Web API Services.

Prerequisites

This article assumes that an account with the Cast Iron Web API is available for use. A trial version will be sufficient. In addition, you should have a good understanding of APIs in general and RESTful services.

To build the proxy in this article, you need the following elements:

  • A valid EveryTrail account that you can query and manipulate. (We suggest that you create your own for testing purposes.)
  • An app ID and secret key to invoke the EveryTrail set of APIs.
  • An admin account for WebSphere Cast Iron Live Web API Services to define your API and configure it to proxy EveryTrail.
  • Any HTTP Poster application to test the solution. (We used Google Chrome's Representational State Transfer [REST] console.)

The EveryTrail application programming interface (API) is, as described on its website, "the best way to share trips, connect with other travelers, and find great new things to do." EveryTrail exposes its web API at its website, and its developer portal lists all the API elements that application developers can use.

The use case in this solution is that of a simple, secure proxy (see Figure 1). EveryTrail provides, at registration, an app ID and secret key that you must provide with every function you intend to invoke. Note that the app ID and the secret key must be the user name and password for HTTP Basic authentication for all of the EveryTrail API. The proxy you will build on IBM WebSphere Cast Iron Live Web API Services will also expose an app ID and secret. To invoke the EveryTrail API, client applications will have to invoke the proxy in WebSphere Cast Iron Live Web API Services. IBM's web API will then relay the EveryTrail app ID and secret key to make the actual call to the EveryTrail API.

Figure 1. Proxying a secure web API (EveryTrail.com)
Image showing the user case for proxying a secure web API

Here is a typical flow of control in this use case:

  1. The client application (mobile or web) invokes an API (say, /api/user/info) in WebSphere Cast Iron Live Web API Services. This client application provides the app ID and key (optional) as a parameter in the request.
  2. The IBM web API receives the request, validates the app ID, and rejects the request if the app ID is not valid.
  3. WebSphere Cast Iron Live Web API Services relays the request to the actual EveryTrail API (/api/user/info) on the EveryTrail server.

Step 1. Create your EveryTrail account

Register at EveryTrail, and create your account. To do so, you need a valid email address so that you can exercise the API exposed and play around with it. Alternatively, you can use a friend's account to query his or her trips.

Note: You don't need to create an EveryTrail account to use the EveryTrail API.

To register at the EveryTrail website, perform the following steps:

  1. Go to http://www.EveryTrail.com, and click the Signup link, shown in Figure 2.
    Figure 2. The EveryTrail Signup page
    Image showing the EveryTrail Signup page
  2. Enter a valid email ID, then provide the required details (see Figure 3).
    Figure 3. Registering your account name
    Image showing how to register your account name
  3. Fill out your profile.

    You will be querying your profile details later, so be sure to put some meaningful text in the comments, too. All you need to fill in is your first name, last name, and few lines in the About Me section (see Figure 4).

    Figure 4. Setting up your profile
    Image showing how to set up your profile

You are done creating an EveryTrail account. Congratulations and happy travels! You will also receive an email on the registered email ID from the EveryTrail team that provides information on the features and capabilities of the website (see Figure 5).

Figure 5. Successful registration email from EveryTrail
Image showing the successful registration email from EveryTrail

Step 2. Create your EveryTrail API keys

You need EveryTrail API keys to access the function running at EveryTrail. Most APIs in the world today use the app ID and secret key combination to provide access to developers' applications.

So, while you are still on the Profile tab, look for a link at the bottom called Developer API (see Figure 6), or simply go to www.EveryTrail.com/developer.

Figure 6. The Developer API link
Image showing the Developer API link

In the EveryTrail developer portal, click the Request new key tab, shown in Figure 7.

Figure 7. Requesting a new key
Image showing how to request a new key

The EveryTrail API requires you to provide the name of the application for which you want to use its API. Provide an application name, a short description of the application, and the platform of your development or mobile app development environment platform (see Figure 8).

Figure 8. Details for your EveryTrail API key
Image showing details for your EveryTrail API key

Remember your key!

Make a note of the key and secret. You will have to let WebSphere Cast Iron Live Web API Services know about this key and secret in your API definition. It is this key and secret that the IBM web API uses to invoke the actual EveryTrail API.

When you have finished providing the details, click Request key. EveryTrail generates the API key and secret for you. The API keys are created and displayed on the API Keys tab, as shown in Figure 9.

Figure 9. EveryTrail API keys
Image showing the EveryTrail API keys

Congratulations! You now have the power to invoke APIs at EveryTrail.


Step 3. Build the proxy in WebSphere Cast Iron Live Web API Services

Now, you're ready to develop the middle piece of the integration, the WebSphere Cast Iron Live Web API Services piece. The IBM web API has the capabilities to create, socialize, and manage APIs in an easy-to-use manner. All you need to put the solution together is a browser, an Internet connection, and an account in WebSphere Cast Iron Live Web API Services.

The EveryTrail API is quite rich and, as depicted, has many functions in each of its APIs. Our article, however, uses two important resources from the Users API:

  • The User login resource:
    • URI:/api/user/login
    • Function: Logs the user into the EveryTrail application
    • Request: User name, password (the one you used to create the EveryTrail account)
    • Response: ID of the user
  • The User info:
    • URI:/api/user
    • Function: Retrieves user profile information
    • Request: User ID (retrieved from the Login function)
    • Response: Details of the user's profile (These are the same details you entered during the registration process.)

Now that you know which resources you'll proxy, let's look at what needs to be done in WebSphere Cast Iron Live Web API Services.

To begin the configuration, please keep the following items handy:

  • Your WebSphere Cast Iron Live Web API Services admin login, which you can find in the email you received from "IBM Cast Iron Live"
  • The resources (API functions) from EveryTrail that you want to define and manage from WebSphere Cast Iron Live Web API Services
  • The EveryTrail API app ID and secret key that you created on the EveryTrail developer portal

Define your API

To define your API, perform the following steps:

  1. Log in to the WebSphere Cast Iron WebAPI Builder, shown in Figure 10.
    Figure 10. IBM's web API management portal
    Image showing the IBM web API's management portal
  2. Create your EveryTrail API definition by providing the application name and context.

    Note: Consider your naming convention carefully. The API name refers to one or more functions available in the corresponding API that you will proxy, so use a generic name for a set of APIs.

    Because we are proxying the EveryTrail API, we chose the following information:

    • API name: EveryTrail API
    • Context: everytrail
    • API description: This is Simple Proxy Application for EveryTrail Travel Sites

    When you click Create, you see the page in Figure 11.

    Figure 11. Creating your API definition
    Image showing how to create your API definition

    Notice that the details you entered have been registered as an API; the base URL of the API is also indicated. In our case, the URL is https://webapi.ciweb-stg.castiron.com/everytrail.

  3. Having created the API definition, configure it as a proxy:
    1. Click the pencil mark icon to edit the API.
    2. On the Resource Definition tab, enter the following information:
      • The resource URI
      • A description of the resource
      • The method with which you want to invoke the resource (GET, POST, DELETE, or PUT)
  4. Click Add to add the resource to the API.

    For this example, use the URI, method, and description shown in Figure 12

    Figure 12. Entering the resources for the API
    Image showing how to enter the resources for the API

Tip

WebSphere Cast Iron Live Web API Services allows you to create resources with query parameters. You must define these parameters in the resource URI with the query parameters if your resource requires it. To do so, follow this resource URI pattern: customer/{customer ID}/address?queryparam1=paramvalue1&queryparam2=paramvalue2

Also notice that the text field provides the example resource URI. The help also appears in the tooltip for the Resource URI text field.

You have now defined your first resource in the EveryTrail API for the user login. Later, you will define another one for getting the user's profile information. Figure 13 shows what the Resource Definition tab looks like after you have added the resources.

Figure 13. The resource definitions
Image showing the resource definitions

Tip

Actions in WebSphere Cast Iron Live Web API Services trigger an automatic save action. Tabbing out of text fields or clicking Add, Submit, or Create triggers an automatic save and persists the information permanently. Hence, there are no Save buttons or links anywhere on the pages.

Note the resource URI, the absolute URL that must be used to access the resource from the client, and the edit icon on the right—all circled in red.

At this point, you have only created the definition of the resource. To further configure the proxy details for the resource, click the pencil icon to edit the resource. When done, you see the page shown in Figure 14.

Figure 14. Configuring proxy details for your resource
Image showing how to configure proxy details for your resource

Notice that the two query parameters you had specified in the resource URI (user name and password) have automatically been added. Now, enter a short description of what those parameters mean. In our case, the parameters correspond to the user name and password of the EveryTrail user. Documenting the query parameters at this point ensures proper documentation when you create and publish the developer's portal.

Configure your API

You're now at the point of building a simple proxy. In the WebSphere Cast Iron WebAPI Builder, select the Proxy check box to enable the Forward request to text field. Enter the following text in the text:

http://<<EveryTrail API Key>>:<<EveryTrail API Secret>>@www.everytrail.com/api/user/login

This means that all requests coming to the resource:

https://webapi.ciweb-stg.castiron.com/everytrail/api/user/login?username=
   someusername&password=somepassword

will be forwarded to:

http://<<EveryTrail API Key>>:<<EveryTrail API Secret>>@www.everytrail.com/api/user/login

Important

This is the integration point where you tell WebSphere Cast Iron Live Web API Services to forward the incoming request to the actual back-end web API. It is also important to understand that because the EveryTrail API can be invoked only upon provision of Basic authorization, you need to provide the API key and secret, as specified in the URL.

Along with the parameters, you can, if required, fill in the request and response headers, as shown in Figure 15.

Figure 15. Integration point with EveryTrail
Image showing the integration point with EveryTrail

For our case, because we know about the behavior of the login function, add a sample response. Remember: You are adding a sample response only for the documentation portal. The description of the login use case is provided at http://devwiki.everytrail.com/index.php/User_Login.

Now, copy the text provided in the Success Response section, shown in Figure 16:

Figure 16. The User Login details page
Image showing the User Login details page

and paste it in the Response Body field, as shown in Figure 17.

Figure 17. Adding the response body
Image showing how to add the response body

Important

The Response Body field help suggests that you need to provide an example. At this point, however, this instruction is misleading. The sample XML is actually used by the IBM web API to validate the response. If you do not provide the sample XML, the IBM web API defaults to JavaScript Object Notation (JSON) validation and complains about an invalid JSON format. So, please be sure to fill out the response body.


Step 4. Create the developer portal for the EveryTrail API

The idea here is to use WebSphere Cast Iron Live Web API Services not only to create the proxy for the API but also to enable organizations to quickly publish the same for consuming application developers to use.

Discussing requirements

In reality, clients who want to expose their APIs would typically not have such a portal. A requirements discussion on which API should be published would reveal the details required to create the portal.

EveryTrail provides a developer portal, but for our purposes, assume that you have to build one in WebSphere Cast Iron Live Web API Services. To do so, perform the following steps:

  1. Select Customize Developer Pages from the admin@webapi list at the top right corner of the WebSphere Cast Iron WebAPI Builder (see Figure 18).
    Figure 18. Customizing developer pages
    Image showing how to customize the developer pages
  2. Select the layout and color of your choice.
  3. Upload a logo and a landing page graphic that suits your taste.
  4. Add links to relevant social media portals, such as Twitter.
  5. Add a link to the Terms and conditions information.

Figure 19 shows what we have used to create the look and feel of the portal.

Figure 19. Creating the developer portal for EveryTrail (our customization)
Image showing our customization of the sample EveryTrail developer portal

When you finish furnishing all the details, click Publish at the top right corner. The control flows to the portal that has been created for you. In our example, the portal looks like Figure 20.

Figure 20. The EveryTrail developer portal in WebSphere Cast Iron Live Web API Services
Image showing the sample EveryTrail developer portal in WebSphere Cast Iron Live Web API Services

You have successfully created the developer portal for the EveryTrail API.


Step 5. Register the application

When you are done creating the developer portal, you must register the application with WebSphere Cast Iron Live Web API Services.

Important

This is where WebSphere Cast Iron Live Web API Services provides you with an application ID and secret key that you must use to access and invoke the resources in the API.

To register your application with WebSphere Cast Iron Live Web API Services, sign in with your admin credentials on the portal that you just created. After you sign in, you see the landing page shown in Figure 21.

Figure 21. Registering the application
Image showing how to register the application

You can also get to this page by selecting Show Getting Started from the admin@webapi list, shown in Figure 22.

Figure 22. Logging in to the developer portal
Image showing how log in to the developer portal

To register an application, click the Register Apps link.

Registering an application requires that you provide an application name and some descriptive text about it, as shown in the form in Figure 23. (We called the application EveryTrail Application.) Then, click Add.

Figure 23. Details of the registration
Image showing details of the registration

When WebSphere Cast Iron Live Web API Services is done with the task of registering an app, it provides the following information:

  • An application ID (required)
  • A secret key (optional)

How and when do you use the app ID and key?

When invoking the resource URL using query parameters (if any) append: appId=<<Your unique application ID>>

Also, remember that you may have to provide the secret if the entitlement expects you to provide it. An example URL invocation looks like this: https://webapi.ciweb-stg.castiron.com/everytrail/api/user/login?username=
<<EveryTrailUser>>&password=<<EverytrailPassword>>
&appId=5dba54f0-d786-4e2b-ad23-3deaeba45e4f

Make a note of both of these, and store the text somewhere you will remember. You will need the application ID to invoke the API in WebSphere Cast Iron Live Web API Services. A pop-up window provides the ID and secret (remember, you will not receive an email containing the app ID and key), as shown in Figure 24.

Figure 24. Application ID and secret key
Image showing application ID and secret key

You are ready to test your application.

Feel free to define more resources from the EveryTrail API. In our case, we planned to include api/user to retrieve a user's profile information.


Step 6. Test your application

You can test your app by using the Test tab on the Resource Editor tab (see Figure 25). To do so, perform the following steps:

  1. Select the resource you want to test.
  2. Select the application you want to test with. (This step specifies the app ID to be appended to the invoking URL.)
  3. In the Parameters section, fill in the expected parameters.

    In this example, it's the EveryTrail user name and password.

  4. Click Test.
Figure 25. Testing the app
Image showing how to test your app

Conclusion

You have successfully built a proxy for a publicly available API using IBM WebSphere Cast Iron Live Web API services. We look forward to your feedback.

Acknowledgment

We would like to thank Ian Heritage for helping us crack the integration where we were stuck for a whole day. Also, we thank Alan Moore for providing all the input we needed to understand EveryTrail integration.

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Mobile development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, Cloud computing, WebSphere
ArticleID=863889
ArticleTitle=Build a simple proxy for the EveryTrail public API using IBM WebSphere Cast Iron Live Web API Services
publish-date=04052013