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)
Here is a typical flow of control in this use case:
- 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.
- The IBM web API receives the request, validates the app ID, and rejects the request if the app ID is not valid.
- 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:
- Go to
http://www.EveryTrail.com, and click the Signup link, shown in Figure 2.
Figure 2. The EveryTrail Signup page
- Enter a valid email ID, then provide the required details (see
Figure 3. Registering your account name
- 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
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
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
Figure 6. 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
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
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
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
- 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
- Function: Retrieves user profile information
- Request: User ID (retrieved from the
- 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:
- Log in to the WebSphere Cast Iron WebAPI Builder, shown in
Figure 10. IBM's web API management portal
- Create your EveryTrail API definition by providing the application name
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
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
- Having created the API definition, configure it as a proxy:
- Click the pencil mark icon to edit the API.
- On the Resource Definition tab, enter the
- The resource URI
- A description of the resource
- The method with which you want to invoke the resource
- 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
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
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
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:
will be forwarded to:
http://<<EveryTrail API Key>>:<<EveryTrail API Secret>>@www.everytrail.com/api/user/login
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
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
Now, copy the text provided in the Success Response section, shown in Figure 16:
Figure 16. The User Login details page
and paste it in the Response Body field, as shown in Figure 17.
Figure 17. Adding 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.
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:
- 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
- Select the layout and color of your choice.
- Upload a logo and a landing page graphic that suits your taste.
- Add links to relevant social media portals, such as Twitter.
- 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)
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
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.
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
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
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
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)
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
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:
- Select the resource you want to test.
- Select the application you want to test with. (This step specifies the app ID to be appended to the invoking URL.)
- In the Parameters section, fill in the expected parameters.
In this example, it's the EveryTrail user name and password.
- Click Test.
Figure 25. Testing the app
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.
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.
- Find more information about the User Login Resource from the EveryTrail development wiki.
- The EveryTrail development wiki also provides information on User Profile Info.
- Access the WebSphere Cast Iron Live Web API Services management portal.
- At developerWorks Mobile development, find tools for free download, tutorials to get you started, as well as how-to articles and technical perspectives on a range of topics for mobile application developers.