Overview

This is a getting started Guide for the API Management product which provides a platform to build web proxies on top of existing web services to secure them as well as to analyze the footfall to the backend servers.

Prerequisites

Perform the following before setting up the Product.

1. Install the product with the .bin or .exe installer of the product; run the installer which gives you an intuitive wizard to install the Fiorano setup as per your needs.

   Icon

   Further in this document, "$FIORANO_HOME" refers to the Fiorano Setup installation directory.

2. The main prerequisite for the product, apart from JAVA 1.7.0_55 and ANT 1.9.2, are the installation of a Cassandra Database Server and PostGre SQL server.

   1. Cassandra Database is an open source database that provides unmatched linear scalability and high availability with proven fault tolerance and is used to store details that needs to be looked up on the fly.

      Icon

      • Please refer http://planetcassandra.org/cassandra/?action=true for directions to install Cassandra.
      • For now the assumption is that both Management Server and Gateway are in same machine with Cassandra installed in it.
   2. Fiorano uses PostGre SQL for its analytics data store. To configure PostGre SQL for analytics, perform the following actions:
      1. Install PostGre on the machine where you want your Analytics Database to be.
      2. Create your desired username, set the desired password and create the database that you want Fiorano to use for the purpose.
      3. Download the PostGre JDBC driver for your JVM and keep it ready for the later steps.
      4. Once Fiorano is installed, some changes need to be done in the Fiorano setup for the Analytics to connect to the PostGre SQL. To do this, go to $FIORANO_HOME/esb/server/profiles/server1/AMS/conf/apidb.cfg and make the following changes:
         
         1. Under section 2 of this document, change the <ip-address>, <port> and <database> variables to the actual desired settings of the above installed PostGre setup.
         2. Under section 3 and section 4 of this document, provide the username and password credentials needed to connect to the installed database.
         3. Under section 6 and 7, provide the reconnect settings of your choice.
         4. Go to $FIORANO_HOME/esb/server/bin/server.conf and under the <java.classpath> segment, add the path to the above downloaded JDBC driver, so that the driver gets added to the classpath of the JVM.

Now you are ready for the set up. You may continue with the steps mentioned in the next section.

Setting up

The following steps will provide you with step by step instructions on how to go about using the product.

Adding product licenses

The Fiorano API installers work with the same license as used by the main Fiorano Platform.

Starting API servers

Fiorano API Management product provides you with two server setups:

• API Management Server (AMS)
• API Gateway Server (AGS)

API Management Server (AMS)

This is the control centre of the API Management product. It is the place from where all the main deployment of your API projects and policies will be controlled.
To start the AMS server, please execute the following command at $FIORANO_HOME/esb/server/bin

• Linux

• Windows

API Gateway Server (AGS)

This is the server on which the projects get deployed. This server will be the place to which the clients will connect before their traffic is stored for analysis and request is redirected to the backend API. There can be multiple Gateway Servers running on a single network controlled by an API Management Server.

To start the AGS server, execute the following command at $FIORANO_HOME/esb/server/bin:

• Linux

• Windows

Fiorano also provides you with a pre-configured second Gateway Server Profile which can also be started by executing the following command at $FIORANO_HOME/esb/server/bin:

• Linux

• Windows

Both the servers should start without any issues, and should display the below content, on console, as a confirmation of having successfully connected to Cassandra database:

================Connected===========================

In case you do not get the above statement on the Server Console and find errors of the following type: "API traffic dataStore Initialization Failed", please check whether the Cassandra DB is running.

Launching the API Dashboard

Fiorano API Management uses a new API Management Dashboard as a client GUI to assist in configuring and maintaining the API servers and projects.

The dashboard is hosted at the following address after the starting of the AMS server:

After logging in with the User name and Password credentials, the Dashboard Home page looks as in the following figure.

Figure 1: Fiorano API Management Dashboard Home page

Creating an Environment for Project Deployments

To develop and deploy API projects, a new environment needs to be created, which can be done by performing the following actions:

1. Go to the API Management Dashboard and click the Admin prompt.
2. Select the Environments tab, and click the Add  button to add an environment in the Environments selection box.
3. After adding the environment, select the added environment. It will show a Servers selection box where you can define on which server to deploy the environment-specific projects. Click Edit  button to see the sections:
   
   • Servers: Lists the Server already added.
   • Available Servers: Lists the servers available to be added.
4. Add a running Gateway Server to the above list and click Save to save the environment changes.
   
   
   Figure 2: Adding a Gateway Server

Adding a Backend Project

To add a proxy project to an existing backend REST/HTTP service, perform the following actions:

1. Go to the API Management Dashboard and click the API Projects prompt to navigate to the API Projects page.
2. On the upper-right part of the screen, select From REST/HTTP Service option from the Add API Project drop-down list.
   
   
   Figure 3: Navigating to New Backend Service dialog box
   
   
3. Provide the details of this API project in the New Backend Service dialog box that appears. Provide the Display name, Backend Service URL and Project Context Path, and set the method needed for both Backed Service URL and Project Context Path in the corresponding method fields given.
   Example: URL: - http://www.thomas-bayer.com/sqlrest Method : GET.
   
   
   Figure 4: New Backend Service dialog box
   
   
4. Click OK to finish editing and save project to repository.

5. On the upper-right part of the page, click the small drop-down  button beside (on the right) the Deploy  button to list available deployment environments, select the desired environment to deploy your project.

   Icon

   Beside the Deploy button, you may also find an Un-deploy  button; click the arrow beside it to list the environments available and select the environment from which you want to un-deploy this project.

Adding Policies

Policies are used to enforce various modifications/security checks. To add a policy, please perform the following actions in the API Management Dashboard:

1. From Home page, click the API Projects prompt to navigate to API Projects page where the projects added will be listed.
2. Double-click the project to which the policy is to be added.
3. Select the Policies tab and click the Add  button (Add new policy configuration) on this tab to add a new policy.
4. In the Add New Policy pop-up, add a policy ID and select the type of policy to be added (Eg: Security > IP Filtering) from the Policy drop-down and click OK.
   
   
   Figure 5: Add New Policy dialog box
   
   
5. Select the Policy ID to navigate to the respective Policy Configuration page.
6. In the Policy Configuration page, configure the policy as per your need, for example, if you want to deny IP network 192.168.1.0, provide "192.168.1.0/24" in the DeniedIP with Mask text box and select Allow/Deny in No Match Rule text box as per your requirement.
7. Click Save  button present at the upper-right part of the screen to apply the changes to the project; a confirmation message flashes for 2 seconds in the background.

Attaching a Policy to Proxy Flow

After adding policies, to attach the created policy to a Project, perform the following actions:

1. Under the same window, click the Resources tab.
2. A resource named 'DefaultResource' will already be present under the tab; you may add a new resource or edit the Default Resource.
3. Click on the resource to view the resource editor on the right side. Policies can be attached at 4 places, each of them appearing as an arrow on the resource editor.
   1. Selecting any of these arrows will open an editor window.
   2. Click the Edit button beside the editor to display the below sections:
   • • Policies: Lists the policies (added to that endpoint)
     • Available Policies : Lists the policies available to be added.
4. Select the required policies and add them to the endpoint by dragging it from Available Policies section to Policies section or by using the Arrow button available between the sections.
5. After this is done, click Save  button to apply the changes and to attach your policy to the project

Testing a Deployed Service

By default, the gateway server of server1 profile listens to port: 2160 enabling access to the deployed API projects/products.

To access the deployed backed service, you can use the URL in the following format:

If this returns the desired outcome, after calling the backed service API, that means your project is successfully configured.

Adding a WSDL Project

WSDL projects are used to convert SOAP-based APIs to RESTful APIs. To add a WSDL Project, perform the following actions in the API Management Dashboard:

1. Click the API Projects prompt to navigate to the API Projects page.
2. On the upper-right part of the screen, select From WSDL file option from the Add API Project drop-down list.
3. Provide the details of this API project in the New WSDL Project dialog box that appears; add display name, context path and provide the WSDL file/URL for the WSDL service.
   
   
   Figure 6: New WSDL Project dialog box
   
   
4. Click OK to save the WSDL configuration.

This should automatically fetch the WSDL details and create the project with attached policies; you may add more policies as needed.

Deploy the project and we are good to go.

Adding Products, Clients and Client Subscriptions

Click the Apps prompt in the API Management Dashboard and follow the sections below to add a product, add Clients and add Client Subscriptions respectively.

To add a Product

1. Click the Products tab, and click the Add  button to add a new product.
2. Provide the desired Product ID in the New Api Product pop-up and click OK.
3. Select the Product ID to navigate to navigate to the respective Product Configuration page.
4. Configure the product as per your requirement and add the desired projects to this product using projects selection box at the bottom of this page. Click  Edit  button to see the sections:
   • Projects in Product: Lists the projects added in the Product.
   • Available projects: Lists the projects available to be added.
5. Click Save button present at the bottom of the screen to add the product.

To add a Client

1. Click the Clients tab and click the Add  button to add a new client.
2. Provide the desired Client ID in the New Client pop-up and click OK.
3. Select the Client ID to navigate to the respective Client Configuration page.

4. Configure the client details such as Client Name, Email and Status as per requirement.

5. And the desired attributes and corresponding values by clicking Add  button and then adding values under Attribute and Value columns respectively.

   Icon

   Use Delete icon to remove an attribute.

6. Click Save button present at the bottom of the screen to add the client.

To Add a Client Subscription

Client Subscription is basically a combination of single client and multiple products. To add a Client Subscription, perform the following actions under Apps prompt:

1. Click the Client Subscriptions tab and click the Add  button to add a new subscription.
2. Provide the desired Client Subscription ID in the New Client Subscription pop-up and click OK.
3. Select the Client Subscription ID to navigate to the respective Client Subscription Configuration page.
4. Configure the Client Subscription details as per requirement and click Save.
5. Add the necessary products to the app. You may edit the properties in the Properties section.
6. Click Save to add the Client Subscription.

After the Client Subscription is created, click the project selected in the API Products section to display the Consumer Key and Consumer Secret number. These digits can be changed by clicking Regenerate button.

For secure access to this project, the generated key and secret need to be passed while calling the API.

Figure 7: Consumer Key and Consumer Secret numbers appearing as API Product Info

Verify API Key Policy

Adding Verify API Key Policy

To add a Verify API Key Policy, please perform the following actions in the API Management Dashboard:

1. Click the API Projects prompt.
2. Double-click the project to which the policy is to be added.
3. Select the Policies tab and click the Add  button to add a new policy.
4. In the Add New Policy pop-up, add a policy ID and select the type of policy to be added (Eg: Security > Verify API Key) from the Policy drop-down and click OK.
5. Select the Policy ID to navigate to the respective Policy Configuration page.
6. Configure the Key Source as needed by clicking the Edit  button and then click Save to add the policy.

After the policy is created, attach this policy to the project by performing the following actions under the same page:

1. Go to the Resources tab.
2. You may edit the DefaultResource which is already present here or you may add a new resource. Click the resource to open the resource editor and then attach this policy to the proxy request endpoint.
3. Click Save to attach the policy to the project.

Now you can deploy the project with the Verify Key Policy attached to the project.

Testing the policy

To test this policy, perform the following actions:

1. Create a sample Verify API Key policy (referring to Adding Verify API Key Policy section above) with the following configuration in Key Source:
   • Type: PARAMETER
   • Name: APIKey
   • Default value: Provide a value of your choice.
2. Create Client Subscription by following the steps mentioned in Adding Products, Clients and Client Subscriptions section, and deploy the project.
3. From the Client Subscriptions listing (API Products section under Client Subscription Configuration), get the Consumer Key.

4. Pass this value to the API proxy access URL on the gateway server as a parameter in the following format:

If the Consumer Key is correct, the request should succeed, else an Authentication failure code will be displayed.