Versions Compared

Old Version 19

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community and for routing API traffic in a scalable manner. It leverages the integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, and WSO2 Governance Registry. In addition, as it is powered by the WSO2 Business Activity Monitor (BAM), the WSO2 API Manager is ready for massively scalable deployment deployments immediately.

This guide walks you thorough the main use cases basic usecases of the API Manager:

Table of Contents
maxLevel3
minLevel3

...

Table of Contents
maxLevel54
minLevel54
typeflat

Components

The API Manager comprises of the following components:

  • API Gateway: Secures, protects, manages, and scales API calls. It is a simple API proxy that intercepts API requests and applies policies such as throttling and security checks. It is also instrumental in gathering API usage statistics. The Web interface can be accessed via https://<Server Host>:9443/carbon.
  • API Key Manager: Handles all security and key-related operations. API gateway connects with the key manager Key Manager to check the validity of OAuth tokens when the APIs are invoked. The Key Manager also provides a token API to generate OAuth tokens that can be accessed via the Gateway.
  • API Publisher: Enables API providers to publish APIs, share documentation, provision API keys, and gather feedback on API features, quality and usage. The You access the Web interface can be accessed via https://<Server Host>:9443/publisher.
  • API Store: Enables API consumers to self register, discover API functionality, and subscribe to APIs, evaluate them and interact with API publishers. The You access the Web interface can be accessed via https://<Server Host>:9443/store.
  • Additionally, statistics are provided by the monitoring component, which integrates with WSO2 BAM.

Users and roles

The API manager offers three distinct community roles that are applicable to most enterprises:

  • Creator: a A creator is a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions, how it is exposed by API the Gateway etc.) and uses the API publisher to provision APIs into the API storeStore. The creator uses the API Store to consult ratings and feedback provided by API users. Creator Creators can add APIs to the store but cannot manage their lifecycle life cycle (i.e., make them visible to the outside world).
  • Publisher: a A publisher manages a set of APIs across the enterprise or business unit and controls the API lifecycle life cycle and monetization aspects. The publisher is also interested in usage patterns for APIs and as such has access to all API statistics.
  • Consumer: a A consumer uses the API store to discover APIs, see the documentation and forums and rate/comment on the APIs. S/he subscribes to APIs to obtain API keys.

API

...

life cycle

An API is the published interface, while the service is the implementation running in the backend. APIs have their own lifecycles life cycles that are independent to of the backend services they rely on. This lifecycle life cycle is exposed in the API publisher Publisher Web interface and is managed by the API publisher role.

The following stages are available in the default API life cycle:

  • CREATED: API metadata is added to the API Store, but it is not visible to subscribers yet, nor deployed to the API gatewayGateway
  • PROTOTYPED: The API is deployed and published in the API Store as a prototype. A prototyped API is usually a mock implementation made public in order to get feedback about its usability. Users cannot subscribe to a prototyped API. They can only try out its functionalitya prototyped API without subscribing to it.
  • PUBLISHED: The API is visible in the API Store and available for subscription.
  • DEPRECATED: The API is still deployed into in the API Gateway (i.e., available at runtime to existing users) but not visible to subscribers. An You can deprecate an API can automatically be deprecated when a new version of it is published.
  • RETIRED: The API is unpublished from the API gateway Gateway and deleted from the storeStore.
  • BLOCKED: Access to the API is temporarily blocked. Runtime calls are blocked and the API is not shown in the API Store anymore.

You can manage the API and service lifecycles life cycles in the same governance registry/repository and automatically link them. This feature is available in WSO2 Governance Registry (version 4.5 onwards).

Applications

An application is primarily used to decouple the consumer from the APIs. It allows you to do the following:

  • Generate and use a single key for multiple APIs
  • Subscribe multiple times to a single API with different SLA levels

You create an application to subscribe to an API. The API Manager comes with a default application and you can also create as many applications as you like.

Throttling tiers

Throttling tiers are associated to an API at subscription time. They define the throttling limits enforced by the API gatewayGateway. E.g., 10 TPS (transactions per second). You define the list of tiers that are available for a given API at the publisher level. The API Manager comes with three predefined tiers (Gold/Silver/Bronze) and a special tier called Unlimited, which you can be disabled disable by editing the <TierManagement> element of <APIM_HOME>/repository/conf/api-manager.xml file. To edit existing tiers or create your own tiers, see Adding new Throttling Tiers. 

API keys

The API Manager supports two scenarios for authentication:

  • An access token is used to identify and authenticate a whole application
  • An access token is used to identify the final user of an application (for example, the final user of a mobile application deployed on many different devices)

Application access

...

tokens

Application access tokens are generated by the API consumer and must be passed in the incoming API requests. The API Manager uses the OAuth2 standard to provide key management. The An API key is a simple string that you pass to with an HTTP header (e.g., "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a") and it works equally well for SOAP and REST calls.

Application access tokens are generated at the application level and valid for all APIs that are associated you associate to the application. These tokens have a fixed expiration time, which is set to 60 minutes 3600 seconds by default. You can change this to a longer time, even for several weeks. Consumers can re-generate regenerate the access token directly from the API Store Web interface. To change the default expiration time, you open the <APIM_HOME>/repository/conf/identity.xml file and change the value for of the element <ApplicationAccessTokenDefaultValidityPeriod>. You If you set a negative value to <ApplicationAccessTokenDefaultValidityPeriod> element to never expire the application access token.

...

, the token never expires. This value only applies to the new applications you create.

Application user access token

You can generate access tokens on demand using the token Token API. In case a token expires, you use the token Token API to refresh it.

Application user access tokens have a fixed expiration time, which is 60 minutes by default. You can update it to a longer time , such as several weeks, by editing the <ApplicationAccessTokenDefaultValidityPeriod> element in the <APIM_HOME>/repository/conf/identity.xml file.

...

To generate a new access token, you issue a token Token API call with the above parameters where grant_type=password. The Token API then returns two tokens: - an access token and a refresh token. The access token can then be stored is saved in a session on the client side (the application itself does not need to manage users and passwords). On the API Gateway side, the access token is validated for each API call. When the token expires, you refresh the token by issuing a token API call with the above parameters where grant_type=refresh_token and passing the refresh token as a parameter.

API

...

resources

An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API. API resources accept the following optional attributes:

  • verbs verbs: Specifies the HTTP verbs a particular resource accepts. Allowed values are GET, POST, PUT, OPTIONS, DELETE. Multiple values can be specifiedYou can give multiple values at once.  
  • uri-template template: A URI template as defined in http://tools.ietf.org/html/rfc6570 (e.g., /phoneverify/<phoneNumber>)  
  • url-mapping mapping: A URL mapping defined as per the servlet specification (extension mappings, path mappings and exact mappings)  
  • Throttling tiers: Limits the number of hits to a resource during a given period of time. For more information, see  Throttling.
  • Auth-Type: Specifies the Resource level authentication along the HTTP verbs. Auth-type can be None, Application or Application User.  
    • None : Can access the particular API resource without any access tokens 
    • Application: Application An application access token is required to access the API resource
    • Application User: User A user access token is required to access the API resource  

...

  1. Download WSO2 API Manager from http://wso2.com/products/api-managermanagement/try-it.
  2. Install Oracle Java SE Development Kit (JDK) version 1.6.24 or later or 1.7.*.
  3. Set the JAVA_HOME environment variable.
  4. Using the command line, go to <Installation directory> <APIM_HOME>/bin and execute wso2server.bat (for Windows) or wso2server.sh (for Linux).
  5. Wait until you see the message "WSO2 Carbon started in 'n' seconds."
    It indicates that the " where 'n' can be any number of seconds. 
The server started successfully. To stop the API Manager, simply hit Ctrl-C in the command window.

Creating users and roles

In section Users and roles, we  we introduced you to a set of users that are commonly found in many enterprises. To create these users in the API Manager, you Let's see how you can log in to the management console as an administration user (credentials: admin/admin). The admin use can play the creator, publisher and subscriber roles described earlier. In this section, we explain how to set up these users or custom users and roles.

...

Management Console as an admin and create these roles.

  1. Log in to the Management Console (https://<hostname>:9443/carbon) of the API Manager using admin/admin credentials.

  2. Select the Users and Roles menu under the Configure menu.
    Image Added
  3. Click the Roles link and then click Add New Role and provide creator as .
    Image Added
  4. Give the role name as creator and click Next.
  5. Click Next.
  6. Image Added
  7. A list of permissions opens. Select the following permissions from the list that opens and click Finish.
    • Configure > Governance and all underlying permissions.
    • Login
    • Manage > API > Create  
    • Manage > Resources > Govern and all underlying permissions    

    Image Added

  8. Similarly, create the publisher role with the following permissions.

    • Login
    • Manage > API > Publish
    Tip
  9. Tip: As the

    Note that the API Manager comes with the subscriber role

    is

    available

    in the API Manager

    by default

    , you do not have to create it. If you want to create a new role with subscriber permissions, you can do so with

    . It has the following permissions

    .

    :

      • Login
      • Manage > API > Subscribe
  10. You can now Note that you have the following roles added:
    Image Added
    Let's create users for each of those the roles. To do so, click  
  11. Click the Users and Roles menu under the Configure menu again.
    Image Added
  12. Click Users.Click the Users link and then click Add New User, provide .
    Image Added
  13. Give the username/password and click Next. For example, lets create a new user by the name apipublisher.
    Image Added

  14. Select the role you want to assign to the user (e.g., creator,  publisher or subscriber) and click and Finish. Given below is a list of usernames and the roles we assign to them in this guide.

    UsernameRole
    apicreatorcreator
    apipublisherpublisher

    Repeat the steps to create at least one user for all rolesImage Added

  15. Similarly, create a new user by the name apicreator and assign the creator role.

Creating an API

An API creator uses the API provider Web application Publisher to create and publish APIs into to the API Store. In this section, we explain how to  Let's create an API and attach add interactive Swagger-based documentation to it.

In this guide, we work with a service exposed by the Cdyne services provider (www.cdyne.com). We use their phone validation service, which has SOAP and REST interfaces and is documented using a WSDL file. This service is documented at : http://wiki.cdyne.com/index.php/Phone_Verification.

Let's create this API and add it to the API Store.

...

 

  1. Open the API Publisher (https://<hostname>:9443/publisher) and log in as apicreator.

  2. Click the Add link and provide the information given in the table below.
    Image Removed Click Implement once you are done.

    FieldValue DescriptionSample value
    Name 
    PhoneVerification
    Name of API as you want it to appear in the API
    store
    Context
    /phoneverify
    URI context path that is used by to API consumers
    Version
    Context
    		 
    /phoneverify
    Version 1.0.0API version (in the form of version.major.minor)

  3. Under the Resources section, create a resource by the name CheckPhoneNumber and select its GET, POST and OPTIONS methods. Once you are done, click Implement.

    Tip

    Tip: Selecting the OPTIONS method is mandatory if you want to allow subscribers to invoke the API using the API Console, which is in the API Store.

    Image Removed

  4. The Implement tab opens. Provide the following information.

    Image Removed

    FieldValueDescription
    Implementation methodBackend endpointIf you have a real backend implementation to your API, select that option. Else, you can specify implementation in-line. The latter approach is usually used in mock-up implementation for prototyped APIs.
    Endpoint typeHTTP endpoint 
    Production endpointhttp://ws.cdyne.com
    Visibility Public
    ResourcesURL patternCheckPhoneNumber
     Request typesGET, POST, OPTIONS

    Image Added

  5. Give the following information in the Implement tab that opens and click Manage once you are done.

    the endpoint is .
    FieldSample value
    Implementation methodBackend
    Endpoint typeHTTP
    Production endpoint

    In this guide, we work with a service exposed by the Cdyne services provider. We use their phone validation service, which has SOAP and REST interfaces. Endpoint is http://ws.cdyne.com/phoneverify/phoneverify.asmx

     

    . 

    This sample service has two operations as CheckPhoneNumber and CheckPhoneNumbers. Let's use CheckPhoneNumber here.

    Endpoint security schemeNon Secured (If secured, user is asked for credentials of the backend service)

    Image Added

  6. Click Manage to go to the Manage tab and provide the following information. 

    Image Removed

     
    FieldValueDescription
    Tier AvailabilityBronze/Gold/Silver/UnlimitedThe API can be available at different level of service; you can select multiple entries from the list. At subscription time, the consumer chooses which tier they are interested in.TransportsHTTP/HTTPS

    Image Added

    Tip

    Tip: For resources that have methods requiring authentication (i.e., Auth Type is not NONE), you set  None  as the Auth type of  OPTIONS  to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway.

  7. Once you are done, click Save. 

Adding API documentation

  1. After creating saving the API, click on its icon thumbnail in the API Publisher to open its details. Select the Docs tab.Click it.

  2. Click on the API's Docs tab and click the Add New Document link. Image Removed

    Documentation can be provided


    Image Added

  3. The document options appear. Note that you can create documentation inline, via a URL or as a file. For inline documentation, you can edit the content directly from the API publisher interface. You get several documents types:

    • How To
    • Samples and SDK
    • Public forum / Support forum (external link only)
    • API message formats
    • Other
  4. Select the

    Create a 'How To

    type, a name for the document and a short description, which will appear in the API Store. Select inline or provide a URL.
  5. Click Add Document.

  6. ,' using in-line content as the source. The document name is SimpleClient and click the Add Document button.
    Image Added

Subscribing to the API

You subscribe to APIs using the API Store Web application.

  1. Open the API Store (https://<hostname>:9443/store) using your browser.

  2. The API you published earlier is available in the API Store. Self sign up to the API Store using the Sign-up link.
    Image Removed

  3. After subscription, log in to the API Store and click the API you published earlier (PhoneVerification 2.0.0).

  4. Note that you can see the subscription option in the right hand side of the UI after logging in. Select the default application and Bronze tier, and click Subscribe.
    Image Removed

    Applications

    An application is a logical collection of one or more APIs, and is required when subscribing to an API. You can subscribe to multiple APIs using the same application. Instead of using the default application, you can also create your own by selecting the New Application... option in the above drop-down list or by going to the My Applications menu in the top menu bar.

  5. Once the subscription is successful, go to My Subscriptions page.
  6. In the My Subscriptions page, click the Generate buttons to generate production and sandbox access tokens and consumer key/secret pairs for the API.
    Image Removed
You are now successfully subscribed to the API and are ready to start using it.

Invoking the API

To invoke an API, you can use the integrated Swagger interactive documentation support (or any other simple REST client application or curl).

  1. Log in to the API Store (https:/ /<YourHostName>:9443/store).

  2. Click the APIs menu in the API Store and then click on the API that you want to invoke. When the API opens, go to its API Console tab.
    Image Removed

  3. Note the changes you did in the Swagger definition earlier displayed on the console. For example, expand the GET method and see the two parameters that you added:
    Image Removed
    Let's invoke this API using the API Console.

  4. Click the GET method, provide the required parameters and click Try it Out . The parameters you give here change depending on the backend implementation of the API. 

    Query ParametersE.g., PhoneNumber=18006785432&LicenseKey=0AuthorizationThe API console is automatically populated by the access token that you generated in step 9 after subscribing to the API. Base URL

    Appears at the bottom of the console. Using the base URL and the parameters, the system creates the API URL in the form http://<host_name>:8280/<context>/<version>/<Resource, if any><back end service requirements included as parameters, if any>. For example, http://localhost:8280/phoneverify/2.0.0/CheckPhoneNumber. /phoneverify is the context, 2.0.0 is the version, and CheckPhoneNumber is the resource.

    Tip

    Once the document is added, click Edit Content link , which associated with it to opens an embedded editor to edit the document contents.

Versioning the API

Next, we will create a new version of this API.

  1. Log in to the API Publisher as apicreator if you are not logged in already.
  2. Click on the PhoneVerification API and then the Copy button that appears in its Overview tab.
    Image Removed
  3. Specify a new version number in version.major.minor format (e.g., 2.0.0) and click Done.

A new version of the API is created. It is a duplication of all the contents of the original API, including the documentation. The API is now ready to be published. This is done by a user in the publisher role.

Publishing the API

  1. Log in to the API Publisher Web application as apipublisher.
  2. Click on the PhoneVerification API version 1.1.0 that you created before. Note that you can now see a tab as API Lifecycle in the API Publisher UI.
  3. Go to the Lifecycle tab and select the state as PUBLISHED from the drop-down list.
    Image Removed
    • Propagate Changes to API Gateway: Used to define an API proxy in the API Gateway runtime component, allowing the API to be exposed to the consumers via the API Gateway. If this option is left unselected, the API metadata will not change and you will have to manually configure the API Gateway according to the information published in the API Store.
    • Deprecate Old Versions: If selected, any prior versions of the API will be set to the DEPRECATED state automatically.
    • Require Re-Subscription: Invalidates current user subscriptions, forcing users to subscribe again.
The API is now published and visible to consumers in the API store.

Adding interactive documentation

The API Manager provides facility to add interactive documentation support through the integration of Swagger. Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. In Swagger, when APIs are described in simple static JSON representation, they can be loaded through the Swagger UI, which in turn provides the interactive documentation.

When an API is created, the JSON representation of that API is automatically generated and saved into the registry as API definition. This definition describes the API with the information provided at the API creation level. You can customize the automatically generated API definition as follows:

...

When the Swagger definition of the API opens, document the parameters required by the API Console.
For example, the PhoneVerification API requires a telephone number and a license key. You can document this by adding the following under the parameters section of the GET method:

Code Block
parameters:
   - description: Request Body
     name: body
     allowMultiple: false
     required: true
     type: string
     paramType: body
   - description: Give the phone number to be validated
     name: PhoneNumber
     type: string
     required: "True"
     paramType: query
   - description: "Give the license key. If you don't have any, enter 0"
     name: LicenseKey
     type: string
     required: "True"
     paramType: query

...

  1. Image Added

  2. Enter your API's documentation.
    Image Added

Adding interactive documentation

The API Manager provides facility to add interactive documentation support through the integration of Swagger. Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. You describe APIs in simple, static JSON representation through the Swagger API definition in the API Store. When an API is created, the JSON representation of that API is automatically generated and saved in the registry. This definition reflects the information you provide at the API creation stage. You can customize it as follows:

  1. Open the API Publisher (https://<hostname>:9443/publisher) and log in as apicreator if you haven't done so already.
  2. Click the PhoneVerification API to open it and then click the Edit link right next to the API's name. This opens the API in its edit mode.
    Image Added
  3. Click the Edit Swagger Definition button.
    Image Added

  4. When the Swagger definition of the API opens, navigate to the GET method, add the following parameters to it and remove the existing body parameter. The code is given below:

    Anchor
    thisStep
    thisStep

    Code Block
    parameters:
   - description: Give the phone number to be validated
     name: PhoneNumber
     type: string
     required: "True"
     paramType: query
   - description: "Give the license key. If you don't have any, enter 0"
     name: LicenseKey
     type: string
     required: "True"
     paramType: query
  5. Click Save once the changes are done. In a later section, we will see how these parameters appear to subscribers in the API Console of the API Store.

Versioning the API

Let's create a new version of this API.

  1. Log in to the API Publisher as apicreator if you are not logged in already.
  2. Click on the PhoneVerification API and then the Copy button that appears in its Overview tab.
    Image Added

  3. Give a new version number (e.g., 2.0.0) and click Done.
    Image Added

    Tip

    Tip: The Default Version option means that you make this version the default in a group of different versions of the API. A default API can be invoked without specifying the version number in the URL. For example, if you mark http://host:port/youtube/2.0 as the default version when the API has 1.0 and 3.0 versions as well, requests made to http://host:port/youtube/ get automatically routed to version 2.0. 

    If you mark any version of an API as the default, you get two API URLs in its Overview page in the API Store. One URL is with the version and the other is without. You can invoke a default version using both URLs.

    If you mark an unpublished API as the default, the previous default, published API will still be used as the default until the new default API is published (or prototyped).

A new version of the API is created. It is a duplication of the original API, including its documentation. The PhoneVerification 2.0.0 API is now ready to be published. This is typically done by a user in the publisher role.

Publishing the API

  1. Log in to the API Publisher as apipublisher that you created earlier in this guide.
  2. Click on the PhoneVerification API version 2.0.0. Note that you now see a tab by the name Lifecycle in the API Publisher.
  3. Go to the Lifecycle tab and select the state as PUBLISHED from the drop-down list. 
    Image AddedThe three checkboxes mean the following:
    • Propagate Changes to API Gateway: Used to define an API proxy in the API Gateway runtime component, allowing the API to be exposed to the consumers via the API Gateway. If this option is left unselected, the API metadata will not change and you will have to manually configure the API Gateway according to the information published in the API Store.
    • Deprecate Old Versions: If selected, any prior versions of the API that are published will be set to the DEPRECATED state automatically.
    • Require Re-Subscription: Invalidates current user subscriptions, forcing users to subscribe again.
  4. Go to the API Store (https://<hostname>:9443/store) using your browser and note that the PhoneVerification 2.0.0 is visible under the APIs menu.
    Image Added
You have now published an API to the API Store. It is ready to be used by subscribers. 

Subscribing to the API

You subscribe to APIs using the API Store.

  1. Open the API Store (https://<hostname>:9443/store).

  2. Self sign up to the API Store using the Sign-up link.
    Image Added

  3. After signing up, log in to the API Store and click the API that you published earlier (PhoneVerification 2.0.0).

  4. Note that you can now see the subscription options on the right hand side of the UI. Select the default application and Bronze tier, and click Subscribe.

    Image Added

  5. Once the subscription is successful, choose to go to the My Subscriptions page.

  6. In the My Subscriptions page, click the Generate buttons to generate access tokens that you need to invoke the API.
    Image Added

    Tip

    Tip: You can set a token validity period in the given text box. By default, it is set to one hour. If you set a minus value (e.g., -1), the token will never expire.

You are now successfully subscribed to an API. Let's invoke it.

Invoking the API

Let's invoke the API using the integrated Swagger-based API Console.

  1. Click the APIs menu in the API Store and then click on the API that you want to invoke. When the API opens, go to its API Console tab.
    Image Added

  2. Expand the GET method of the resource CheckPhoneNumber. Note the parameters that you added in this step now appearing with their descriptions in the console.
    Image Added

  3. Give sample values to the PhoneNumber and LicenseKey and click Try it Out to invoke the API. 

    Tip

    Tip: If you cannot invoke the API's HTTPS endpoint (causes the SSLPeerUnverified exception), it could be because the security certificate issued by the server is not trusted by your browser. To resolve this issue, access the HTTPS endpoint directly from your browser and accept the security certificate.

    Image Removed Image Added

  4. Note the response for the API invocation. As we used a valid phone number in this example, the response is valid.
    Image RemovedImage Added

 You You have invoked an API using the Swagger API consoleConsole.

Monitoring APIs and viewing statistics

...

  • Number of subscriptions per API (across all versions of an API)
  • Number of API calls being made per API (across all versions of an API)
  • The subscribers who did the last 10 API invocations and the APIs/versions they invoked

  • Usage of an API and from which resource path (per API version)

  • Number of times a user has accessed an API
  • The number of API invocations that failed to reach the endpoint per API per user
  • API usage per application
  • Users who make the most API invocations, per application

  • API usage from resource path, per application

Configuring statistics

...

Tip

If you are on

...

Windows

...

, note the following:

JDK 1.6.* or 1.7

...

  • If you install JDK in Program Files in the Windows environment, avoid the space by using PROGRA~1 when specifying environment variables for JAVA_HOME and PATH. Else, the server throws an exception.
  • Install Cygwin (http://www.cygwin.com

...

  • .) WSO2 BAM analytics framework depends on Apache Hadoop, which requires Cygwin in order to run on Windows. Install at least the basic net (OpenSSH,tcp_wrapper packages) and security related Cygwin packages. After Cygwin installation, update the PATH variable with C:/cygwin/bin and restart BAM.

Steps below explain how to configure WSO2 BAM 2.45.10 with the API ManagerManager. Let's do the configurations first.

  1. Do the following changes in <APIM_HOME>/repository/conf/api-manager.xml file:

    • Enable API usage tracking by setting the <APIUsageTracking> element to true
    • Set the Thrift port to 7614
    • Uncomments and set the data source used for getting BAM statistics in <DataSourceName> element.
    • Set <BAMServerURL> to tcp://<BAM host IP>:7614/ where <BAM host IP> is the machine IP address. Do not use localhost unless you're in a disconnected mode.
    Code Block
    languagexml
    <APIUsageTracking> <!-- Enable/Disable the API usage tracker. --> <Enabled>true</Enabled> <PublisherClass>org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass> <ThriftPort>7614</ThriftPort> <BAMServerURL>tcp://<BAM host IP>:7614/</BAMServerURL> <BAMUsername>admin</BAMUsername> <BAMPassword>admin</BAMPassword>

    /api-manager.xml file:

    • Enable API usage tracking by setting the <APIUsageTracking> element to true
    • Set the Thrift port to 7614
    • Uncomments and set the data source used for getting BAM statistics in <DataSourceName> element.
    • Set <BAMServerURL> to tcp://<BAM host IP>:7614/ where <BAM host IP> is the machine IP address. Do not use localhost unless you're in a disconnected mode.
    Code Block
    languagexml
    <APIUsageTracking>
    <!-- JNDI name of the data source to be used for getting BAM statistics. This data source should
        be defined in the master-datasources.xml file in conf/datasources directoryEnable/Disable the API usage tracker. -->
    <DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>
</APIUsageTracking>

    Specify the datasource definition in <APIM_HOME>/repository/conf/datasources/master-datasources.xml file as follows. 

    Code Block
    languagexml
    <datasource>
 <Enabled>true</Enabled>   
    <PublisherClass>org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>
        <name>WSO2AM_STATS_DB</name><ThriftPort>7614</ThriftPort> 
    <BAMServerURL>tcp://<BAM host IP>:7614/</BAMServerURL>
  <description>The datasource used for getting statistics to API Manager</description> <BAMUsername>admin</BAMUsername>
    <BAMPassword>admin</BAMPassword>
    <!-- JNDI name of the data <jndiConfig>source to be used for getting BAM statistics. This data     <name>jdbc/WSO2AM_STATS_DB</name>source should
        be defined in </jndiConfig>
     the master-datasources.xml file in conf/datasources directory. -->
    <definition type="RDBMS"><DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>
</APIUsageTracking>

  2. Specify the datasource definition in <APIM_HOME>/repository/conf/datasources/master-datasources.xml file as follows. 

    Code Block
    languagexml
    <datasource>
          <name>WSO2AM_STATS_DB</name>
  <configuration>        <description>The datasource used for getting statistics to API Manager</description>
 <!-- JDBC URL to query the database -->  <jndiConfig>
               <url>jdbc:h2:<BAM_HOME>/repository/database/APIMGTSTATS_DB;AUTO_SERVER=TRUE</url><name>jdbc/WSO2AM_STATS_DB</name>
                 <username>wso2carbon</username>   </jndiConfig>
          <definition type="RDBMS">
  <password>wso2carbon</password>           <configuration>
      <driverClassName>org.h2.Driver</driverClassName>           <!-- JDBC URL to query the  <maxActive>50</maxActive>database -->
                 <maxWait>60000</maxWait><url>jdbc:h2:<BAM_HOME>/repository/database/APIMGTSTATS_DB;AUTO_SERVER=TRUE</url>
                 <testOnBorrow>true</testOnBorrow><username>wso2carbon</username>
                 <password>wso2carbon</password>
  <validationQuery>SELECT  1</validationQuery>             <driverClassName>org.h2.Driver</driverClassName>
    <validationInterval>30000</validationInterval>             <<maxActive>50</configuration>maxActive>
          </definition>
</datasource>
    Next, prepare BAM to collect and analyze statistics from API manager.
  3. Download WSO2 BAM 2.4.1 or later from location: http://wso2.com/products/business-activity-monitor.

  4. Change port offset of BAM to 3 by editing the file <BAM_HOME>/repository/conf/carbon.xml file (search for the offset node).

    Code Block
    languagehtml/xml
    <Offset>3</Offset>

    This increments all ports used by the server by 3, which means the BAM server will run on port 9446. Port offset is used to increment the default port by a given value. It avoids possible port conflicts when multiple WSO2 products run in same host.

  5. Do the following changes in <BAM_HOME>/repository/conf/datasources/bam_datasources.xml file:
    • Copy/paste WSO2_AMSTATS_DB definition from API Manager's master-datasources.xml file. You edited it in step 2.

    • Replace the port of WSO2BAM_CASSANDRA_DATASOURCE in URL (jdbc:cassandra://localhost:9163/EVENT_KS). Note that localhost is used here; not the machine IP.

      Note
      • Do not edit the WSO2BAM_UTIL_DATASOURCE, which is using the offset
      • Cassandra is bound by default on localhost, unless you change the data-bridge/data-bridge-config.xml file
  6. Copy the file <APIM_HOME>/statistics/API_Manager_Analytics.tbox to directory <BAM_HOME>/repository/deployment/server/bam-toolbox.
    If this folder is not in the BAM installation directory by default, create it. The toolbox describes the information collected, how to analyze the data, as well as the location of the database where the analyzed data is stored.

    Open <BAM_HOME>/repository/conf/etc/hector-config.xml file and change the port to localhost:9163. You must add the other nodes too when configuring a clustered setup.

    Code Block
    languagexml
    <Nodes>localhost:9163</Nodes>       <maxWait>60000</maxWait>
                 <testOnBorrow>true</testOnBorrow>
                 <validationQuery>SELECT 1</validationQuery>
                 <validationInterval>30000</validationInterval>
            </configuration>
         </definition>
</datasource>

  7. Save the database driver JAR inside both <AM_HOME>/repository/components/lib and <BAM_HOME>/repository/components/lib folders.

    Next, prepare BAM to collect and analyze statistics from API manager.

  8. Download WSO2 BAM 2.5.0 or later from location: http://wso2.com/products/business-activity-monitor.

  9. Change port offset of BAM to 3 by editing the file <BAM_HOME>/repository/conf/carbon.xml file (search for the offset node).

    Code Block
    languagehtml/xml
    <Offset>3</Offset>

    This increments all ports used by the server by 3, which means the BAM server will run on port 9446. Port offset is used to increment the default port by a given value. It avoids possible port conflicts when multiple WSO2 products run in same host.

  10. In <BAM_HOME>/repository/conf/datasources/bam_datasources.xml file, copy/paste WSO2_AMSTATS_DB definition from API Manager's master-datasources.xml file. You edited it in step 2.

  11. Restart the BAM server by running <BAM_HOME>/bin/wso2server.[sh/bat].

Viewing statistics

...

  1. Let's see the statistics now.

  2. Generate some traffic via the API Gateway (invoke the Cdyne API we use in this guide) and wait a few seconds.

...

  1.  

  2. Connect to the API Publisher as a creator or publisher.
    In the publisher role, you are able to see all stats and as creator, you see stats specific to the APIs you create.
  3. Click the Statistics menu. We show the sample statistics here, but you will see graphs specific to your instance.
    Image Modified
  4. Similarly, API subscribers can also see statistics though the API Store. Click the Statistics menu as follows:
    Image Modified

...

This concludes the API Manager quick start. You have set up the API Manager and taken a look at its common usecasesgone through the basic usecases of the product. For more advanced usecases, please see the User Guide and the Admin Guide of the API Manager documentation.