This guide walks you thorough the main usecases of the API Manager:
|Table of Contents|
Introduction to basic concepts
Let's take a look at the basic concepts that you need to know before using the API Manager:
|Table of Contents|
The API manager comprises 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
- API Key Manager : Handles all security and key-related operations. API gateway connects with the key manager to check the validity of OAuth tokens when APIs are invoked . 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 Web interface can be accessed via
- API Store : Enables API consumers to self register, discover API functionality, subscribe to APIs, evaluate them and interact with API publishers. The Web interface can be accessed via
- 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 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 Gateway) and uses the API publisher to provision APIs into the API store. The creator uses the API Store to consult ratings and feedback provided by API users. Creator can add APIs to the store but cannot manage their lifecycle (i.e., make them visible to the outside world).
- Publisher : a publisher manages a set of APIs across the enterprise or business unit and controls the API lifecycle and monetization aspects. The publisher is also interested in usage patterns for APIs and as such has access to all API statistics.
- Consumer : 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.
An API is the published interface, while the service is the implementation running in the backend. APIs have their own lifecycles that are independent to the backend services they rely on. This lifecycle is exposed in the API publisher Web interface and is managed by the API publisher role.
- CREATED : API metadata is added to the API Store, but it is not visible to subscribers yet, nor deployed to the API gateway
- PROTOTYPED : 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 functionality.
- PUBLISHED : API is visible in the API Store and available for subscription.
- DEPRECATED : API is still deployed into the API Gateway (i.e., available at runtime to existing users) but not visible to subscribers. An API can automatically be deprecated when a new version is published.
- RETIRED : API is unpublished from the API gateway and deleted from the store
- BLOCKED : Access 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 in the same governance registry/repository and automatically link them. This feature is available in WSO2 Governance Registry (version 4.5 onwards).
An application is primarily used to decouple the consumer from the APIs. It allows you to :
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 are associated to an API at subscription time. They define the throttling limits enforced by the API gateway. 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 can be disabled by editing the <TierManagement>element of <PRODUCT_HOME>/repository/conf/api-manager.xml file. To edit existing tiers or create your own tiers, see Adding New Throttling Tiers.
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 token
Application access tokens are generated by the API consumer and must be passed in the incoming API requests. The API Manager uses OAuth2 standard to provide key management. The API key is a simple string that you pass to 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 to the application. These tokens have a fixed expiration time, which is set to 60 minutes by default. You can change this to a longer time, even for several weeks. Consumers can re-generate the access token directly from the API Store Web interface. To change the default expiration time, you open
<APIM_HOME>/repository/conf/identity.xml file and change the value for element
<ApplicationAccessTokenDefaultValidityPeriod>. You set a negative value to
<ApplicationAccessTokenDefaultValidityPeriod> element to never expire the application access token.
Application user access token
You can generate access tokens on demand using the token API. In case a token expires, you use the 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
To generate a new access token, you issue a 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 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.
Starting the API Manager
- Download WSO2 API Manager from http://wso2.com/products/api-manager/.
- Install Oracle Java SE Development Kit (JDK) version 1.6.24 or later or 1.7.*.
- Set the JAVA_HOME environment variable.
- Using the command line, go to <Installation directory>/bin and execute wso2server.bat (for Windows) or wso2server.sh (for Linux).
- Wait until you see the message "WSO2 Carbon started in 'n' seconds."
It indicates that the server started successfully. To stop the API Manager, simply hit Ctrl-C in the command window.
Creating users and roles
In section , we introduced you to a set of users that are commonly found in many enterprises. To create these users in the API Manager, you 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.
Log in to the management console user interface (hostname
<hostname>:9443/carbon) of the API Manager using admin/admin credentials.
- Select the Users and Roles menu under the Configure menu.
- Click Add New Role and provide
creatoras the role name.
- Click Next.
- Select the following permissions from the list that opens and click Finish.
- Manage > API > Create
- Manage > Resources > Govern and all underlying permissions
Similarly, create the
publisherrole with the following permissions.
- Manage > API > Publish
Tip: As the
subscriberrole 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 the following permissions.
- Manage > API > Subscribe
- You can now create users for each of those roles. To do so, click the Users and Roles menu under the Configure menu.
- Click Users.
- Click Add New User, provide the username/password and click Next.
Select the role you want to assign to the user (e.g.,
subscriber) and click Finish. Given below is a list of usernames and the roles we assign to them in this guide.
Username Role apicreator creator apipublisher publisher
Repeat the steps to create at least one user for all roles.
An API creator uses the API provider Web application to create and publish APIs into the API Store. In this section, we explain how to create an API and attach documentation to it.
The Phone Number Validation API
Along In this guide, we work with a service exposed by the Cdyne services provider (www.wdynecdyne.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.
- Open the API Publisher (
https://<YourHostName><hostname>:9443/publisher) and log in as
Click the Add link and provide the information given in the table below.
Field Value Description NamePhoneVerificationName of API as you want it to appear in the APIstoreContext/phoneverifyURI context path that is used by to API consumers Version 1.0.0 API version (in the form of version.major.minor)
- It asks you to create a resource with wildcard characters (/*). Click Yes.
- Note that a resource by the name
defaultgets created as follows.
Click Implement again to go to the
Implementtab and provide the following information.
Field Value Description Implementation method Backend endpoint If 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 type HTTP endpoint Production endpoint http://ws.cdyne.com/phoneverify/phoneverify.asmx Endpoint security scheme Non Secured
If the endpoint is secured, user is asked for credentials of the backend service.
WSDL URL:URL of WSDL file (describing API interface)
Click Manage to go to the
Managetab and provide the following information.
Field Value Description Tier Availability Bronze/Gold/Silver/Unlimited The 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. Transports HTTP/HTTPS
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 following optional attributes:
- verbs : Specifies the HTTP verbs a particular resource accepts. Allowed values are GET, POST, PUT, DELETE. Multiple values can be specified.
- uri-template : A URI template as defined in http://tools.ietf.org/html/rfc6570 ( e.g., /phoneverify/<phoneNumber> )
- url-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 Managing Throttling Tiers.
- Auth-Type: Specifies the Resource level authentication along HTTP verbs. Auth-type can be None, Application or Application User.
- None : Can access the particular API resource without any access tokens
- Application: Application access token required to access the API resource
- Application User: User access token required to access the API resource
- None : Can access the particular API resource without any access tokens
Adding API documentation
After creating the API, click on its icon to open its details. Select the Docs tab.
Click Add New Document link.Documentation can be provided 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:
- Swagger documents
- How To
- Samples and SDK
- Public forum / Support forum (external link only)
- API message formats
- Select the 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.
- Click Add Document.
Once the document is added, click Edit Content link, which opens an embedded editor to edit the document contents.
Adding interactive documentation using Swagger
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 by going to the Doc tab of the
PhoneVerification API in the API Publisher.
You can modify the paths, parameters, descriptions etc. by editing the JSON representation of API definition. For example, in the
PhoneVerification API, we have changed the path for all the HTTP methods of API definition from
/phoneverify/1.0.0/CheckPhoneNumber as follows:
Versioning the API
Next, we will create a new version of this API.
- Log in to the API Publisher as
apicreatorif you are not logged in already.
- Click on the
PhoneVerificationAPI and then the Copy button that appears in its Overview tab.
- Specify a new version number in version.major.minor format (e.g., 1.1.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
- Log in to the API Publisher Web application as apipublisher.
- Click on the
PhoneVerificationAPI version 1.1.0 that you created before. Note that you can now see a tab as API Lifecycle in the API Publisher UI.
- Go to the Lifecycle tab and select the state as
PUBLISHEDfrom the drop-down list.
- 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.
Subscribing to the API
You subscribe to APIs using the API Store Web application.
- Open the API Store (
https://<hostname>:9443/store) using your browser. Using the API Store, you can,
- Search and browse APIs
- Read documentation
- Subscribe to APIs
- Comment on, rate and share/advertize APIs
- Take part in forums and request features etc.
The API you published earlier is available in the API Store. Self sign up to the API Store using the Sign-up link.
After subscription, log in to the API Store and click the API you published earlier (PhoneVerification 1.1.0).
- Note that you can see the subscription option in the right hand side of the UI after logging in. Select the default application,
Bronzetier and click Subscribe.
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.
- Once the subscription is successful, go to My Subscriptions page.
- In the My Subscriptions page, click the Generate buttons to generate production and sandbox access tokens and consumer key/secret pairs for the API. For more information on access tokens, see Working with Access Tokens.
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).
- Log in to the API Store (
- Click the
PhoneVerification 1.1.0API that you published earlier.
- Click the API Console tab associated with the API.
Provide the necessary parameters and click Try it out to call the API. For example, the
PhoneVerificationAPI takes two parameters: the phone number and a license key, which is set to 0 for testing purposes.
Note the following in the above UI:
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:8280/<context>/<version>/<back end service requirements included as parameters>.For example,
Query Parameters Give the API payload as PhoneNumber=18006785432&LicenseKey=0 where /phoneverify is the context and 1.1.0 is the version. The rest of the URL is driven by the backend service requirements. Authorization In the authorization header, pass the application key that was generated at the time a user subscribes to an API. This is prefixed by the string "Bearer". For example, Bearer q6- JeSXxZDDzBnccK3ZZGf5_AZTk.
WSO2 API Manager enforces OAuth security on all the published APIs. Consumers who talk to the API Manager should send their credentials (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.
- The response for the API invocation appears as follows:
- Within a minute after the first API invocation, make another attempt to invoke the API and note that the second invocation results in a throttling error.
This is because you applied a Bronze tier at the time you subscribed to the API and the Bronze tier only allows one API call per minute.
Monitoring APIs and viewing statistics
Both the API publisher and store provide several statistical dashboards. Some of them are as follows:
- 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
Steps below explain how to configure WSO2 BAM 2.4.1 with the API Manager.
Do the following changes in
- Enable API usage tracking by setting the
<APIUsageTracking>element to true
- Set the Thrift port to 7614
- 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 language xml
<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> <!-- 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 directory. --> <DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName> </APIUsageTracking>
- Enable API usage tracking by setting the
Specify the datasource definition in
<APIM_HOME>/repository/conf/datasources/master-datasources.xmlfile as follows.
Code Block language xml
<datasource> <name>WSO2AM_STATS_DB</name> <description>The datasource used for getting statistics to API Manager</description> <jndiConfig> <name>jdbc/WSO2AM_STATS_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <!-- JDBC URL to query the database --> <url>jdbc:h2:<BAM_HOME>/repository/database/APIMGTSTATS_DB;AUTO_SERVER=TRUE</url> <username>wso2carbon</username> <password>wso2carbon</password> <driverClassName>org.h2.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Next, prepare BAM to collect and analyze statistics from API manager.
- Download WSO2 BAM 2.4.1 or later from location: http://wso2.com/products/business-activity-monitor.
Change port offset of BAM to 3 by editing the file
<BAM_HOME>/repository/conf/carbon.xmlfile (search for the offset node).
Code Block language html/xml
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.
- Do the following changes in
WSO2_AMSTATS_DBdefinition from API Manager's
master-datasources.xmlfile. You edited it in step 2.
Replace the port of
WSO2BAM_CASSANDRA_DATASOURCEin URL (
jdbc:cassandra://localhost:9163/EVENT_KS). Note that localhost is used here; not the machine IP.
- 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
- Do not edit the
- Copy the file
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.
<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 language xml
Restart the BAM server by running
- Connect to the API Publisher as a creator or publisher.
In publisher role, you are able to see all stats and as creator, you see stats specific to the APIs you create.
- Click the Statistics menu. We show the sample statistics here, but you will see graphs specific to your instance.
- Similarly, API subscribers can also see statistics though the API Store. Click the Statistics menu as follows:
For more information, see Viewing API Statistics.
This concludes the API Manager quick start. You have set up the API Manager and taken a look at its common usecases. For more advanced usecases, please see the User Guide and the Admin Guide of the API Manager documentation.