Quick Start Guide
WSO2 API Manager is a complete solution for designing and publishing APIs, creating and managing a developer community, and for securing and routing API traffic in a scalable way. It leverages proven components from the WSO2 platform to secure, integrate and manage APIs. In addition, it integrates with the WSO2 analytics platform and provides out of the box reports and alerts, giving you instant insights into the APIs behavior.
Before you begin,
- Install Oracle Java SE Development Kit (JDK) version 1.7.* or 1.8.* and set the
JAVA_HOME
environment variable. - Download WSO2 API Manager.
- Start the API Manager by going to
<APIM_HOME>/bin
using the command-line and executingwso2server.bat
(for Windows) orwso2server.sh
(for Linux.)
Let's go through the use cases of the API Manager:
Invoking your first API
Follow the steps in this section to quickly deploy a sample API, publish it, subscribe to it, and invoke it.
- Open the API Publisher (
https://<hostname>:9443/publisher)
and sign in withadmin/admin
credentials. Click the Deploy Sample API button. It deploys a sample API called
PizzaShackAPI
into the API Manager.This Deploy Sample API option is available only when there are no APIs in API Publisher. if you have already created an API, this option will not be available.
Click
PizzaShackAPI
to open it.
Let's publish this API.Go to the Lifecycle tab and note that the State is
PUBLISHED
. The API is already published to the API Store.Sign in to the API Store (
https://<hostname>:9443/store)
with theadmin/admin
credentials and click on thePizzaShackAPI
API.
Select the default application and an available tier, and click Subscribe.
When the subscription is successful, click View Subscriptions on the information message that appears. Click the Production Keys tab and click Generate Keys to generate an access token to invoke the API.
You have now successfully subscribed to an API. Let's invoke the API using the integrated Swagger-based API Console.
Click the APIs menu again and click the
PizzaShackAPI
to open it. When the API opens, click its API Console tab.
Expand the GET method (which retrieves the menu) and click Try it out.
Note the response for the API invocation. It returns the list of menu items.
You have deployed a sample API, published it to the API Store, subscribed to it, and invoked the API using our integrated API Console.
Understanding the API Manager concepts
Before we look into the API management activities in detail, let's take a look at the basic API management concepts.
Components
The API Manager comprises the following components:
- API Publisher: Enables API providers to publish APIs, share documentation, provision API keys and gather feedback on features, quality and usage. You access the Web interface via
https://<Server Host>:9443/publisher
. - API Store (Developer Portal): Enables API consumers to self register, discover and subscribe to APIs, evaluate them and interact with API Publishers. You access the Web interface via
https://<Server Host>:9443/store
. - 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
. - Key Manager: Handles all security and key-related operations. The API Gateway connects with the Key Manager to check the validity of subscriptions, OAuth tokens, and API invocations. The Key Manager also provides a token API to generate OAuth tokens that can be accessed via the Gateway.
- Traffic Manager: Helps users to regulate API traffic, make APIs and applications available to consumers at different service levels and secures APIs against security attacks. The Traffic Manager features a dynamic throttling engine to process throttling policies in real-time.
- WSO2 API Manager Analytics: Provides a host of statistical graphs, an alerting mechanism on pre-determined events and a log analyzer.
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 the Gateway, etc.) 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. Creators can add APIs to the store but cannot manage their life cycle (e.g., 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 life cycle and monetization aspects.
- Consumer: A consumer uses the API Store to discover APIs, see the documentation and forums, and rate/comment on the APIs. Consumers subscribe to APIs to obtain API keys.
API lifecycle
An API is the published interface, while the service is the implementation running in the backend. APIs have their own lifecycles that are independent of the backend services they rely on. This lifecycle is exposed in the API Publisher and is managed by the 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 Gateway.
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 can try out a 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 in the API Gateway (i.e., available at runtime to existing users) but not visible to subscribers. You can deprecate an API automatically when a new version of it is published.
- RETIRED: The API is unpublished from the API Gateway and deleted from the Store.
- BLOCKED: Access to the API is temporarily blocked. Runtime calls are blocked, and the API is not shown in the API Store anymore.
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 with an API at subscription time and can be defined at an API-level, resource-level, subscription-level and application-level (per token). They define the throttling limits enforced by the API Gateway, e.g., 10 TPS (transactions per second). The final throttle limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together. The API Manager comes with three predefined tiers for each level and a special tier called Unlimited
, which you can disable by editing the <ThrottlingConfigurations>
element of the <APIM_HOME>/repository/conf/api-manager.xml
file.
In API Manager 2.0.0 onwards, Advanced Throttling is enabled by default with following configuration in <API-M_HOME>/repository/conf/api-manager.xml.
<ThrottlingConfigurations> <EnableAdvanceThrottling>true</EnableAdvanceThrottling> ...... <ThrottlingConfigurations>
If you are disabling Advanced Throttling in any case by setting the value of <EnableAdvanceThrottling> false, Advanced Throttling is disabled and basic Throttling mechanism is enabled thereafter. In such a scenario, if you want to disable the Unlimited Throttling tier of basic Throttling configurations, you need to disable it under <TierManagement> by setting <EnableUnlimitedTier> to false.
<TierManagement> <EnableUnlimitedTier>true</EnableUnlimitedTier> </TierManagement>
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 token: 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. An API key is a simple string that you pass 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 you associate 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 regenerate the access token directly from the API Store. To change the default expiration time, you open the <APIM_HOME>/repository/conf/identity/identity.xml
file and change the value of the element <AccessTokenDefaultValidityPeriod>
. If you set a negative value, the token never expires. Changes to this value are applied only to the new applications that you create.
Application user access token: You generate access tokens on demand using the Token API. In case a token expires, you use the Token API to refresh it.
The Token API takes the following parameters to generate the access token:
- Grant Type
- Username
- Password
- Scope
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 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: Specifies the HTTP verbs a particular resource accepts. Allowed values are GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS. You can give multiple values at once.
- 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.
- 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: An application access token is required to access the API resource.
- Application User: A user access token is required to access the API resource.
Deep diving into the API Manager
Let's take a look at the typical API management activities in detail:
Creating users and roles
In users and roles, we introduced a set of users who are commonly found in many enterprises. Let's see how you can sign in to the Management Console as an admin and create these roles.
Sign in to the Management Console (
https://<hostname>:9443/carbon)
of the API Manager usingadmin/admin
credentials.- Click Add in the Users and Roles section under the Main menu.
- Click Add New Role.
- Give the role name as
creator
and click Next.
- A list of permissions opens. Select the following and click Finish.
- All Permissions > Admin Permissions > Configure > Governance and all underlying permissions
- All Permissions > Admin Permissions > Login
- All Permissions > Admin Permissions > Manage > API > Create
- All Permissions > Admin Permissions > Manage > Resources > Govern and all underlying permissions
Similarly, create the
publisher
role with the following permissions.- All Permissions > Admin Permissions > Login
- All Permissions > Admin Permissions > Manage > API > Publish
Note that the API Manager comes with the
subscriber
role available by default. It has the following permissions:- All Permissions > Admin Permissions > Login
- All Permissions > Admin Permissions > Manage > API > Subscribe
- The roles you added (creator and publisher) are now displayed under Roles.
Let's create users for each of the roles. - Click Add in the Users and Roles section under the Main menu.
- Click Add New User.
- Give the username/password and click Next. For example, let's create a new user by the name
apipublisher
.
Select the role you want to assign to the user (e.g.,
publisher
) and click Finish.
Similarly, create a new user by the name
apicreator
and assign the creator role.
Creating an API from scratch
Let's create an API from scratch.
- Sign in to the API Publisher (
https://<hostname>:9443/publisher)
asapicreator
. - In the APIS menu, click Add New API.
Select the option to design a new API and click Start Creating .
Give the information in the table below.
Field Sample value Name PhoneVerificationContext/phoneverifyVersion 1.0.0 Visibility Public API Definition URL pattern: CheckPhoneNumber
Note that this URL Pattern is the name of one of the resources that we are going to invoke from the backend service.
- Request types: GET, POST
Click Add and then click Next: Implement > to move on to the next page.
Select the Managed API option.
Give the following information and click Next:M anage > once you are done.
Field Sample value Endpoint type HTTP/REST Endpoint 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. To verify the URL, click the Test button next to it.
This sample service has two operations:
CheckPhoneNumber
andCheckPhoneNumbers
. Let's useCheckPhoneNumber
here.Sandbox endpoint Endpoint is http://ws.cdyne.com/phoneverify/phoneverify.asmx. To verify the URL, click the Test button next to it. Provide the following information in the Manage tab. Leave default values for the rest of the parameters in the UI.
Field Value Description Subscription Tiers <Select all available tiers> The API can be available for subscription at different levels of service. They allow you to limit the number of successful hits to an API during a given period. Once you are done, click Save.
Adding API documentation
In the APIS menu, click the thumbnail of the API to open it.
Click on the API's Docs tab and click Add New Document.
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
Create a 'How To' named
PhoneVerification
, specifying in-line content as the source and optionally entering a summary. When you have finished, click Add Document.
Once the document is added, click Edit Content to open an embedded editor.
Enter your API's documentation and click Save and Close.
Adding interactive documentation
WSO2 API Manager has an integrated Swagger UI , which is part of the Swagger project.
Swagger is a 100% open source, standard, language-agnostic specification and a complete framework for describing, producing, consuming, and visualizing RESTful APIs, without the need of a proxy or third-party services . Swagger allows consumers to understand the capabilities of a remote service without accessing its source code and interact with the service with a minimal amount of implementation logic. Swagger helps describe services in the same way that interfaces describe lower-level programming code.
The Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS that dynamically generates documentation from a Swagger-compliant API. Swagger-compliant APIs give you interactive documentation and more discoverability. The Swagger UI has YAML code, and its UI facilitates easier code indentation, provides keyword highlighting, and shows syntax errors on the fly. You can add resource parameters, summaries and descriptions to your APIs using the Swagger UI and download your API definition as YAML or JSON.
Also, see the Swagger 2.0 specification.
- Open the API Publisher (
https://<hostname>:9443/publisher)
and sign in asapicreator
.
- Click the Edit icon for the
PhoneVerification
API. This opens the API in its edit mode.
- Click the Edit Source button under the API Definition section.
The definition of the API opens as a YAML code in a separate page. Expand its GET method, add the following parameters and click Apply Changes.
parameters: - in: query name: PhoneNumber description: Give the phone number to be validated type: string required: true - in: query name: LicenseKey description: Give the license key as 0 for testing purpose type: string required: true
- Back in the API Publisher, note that the changes you did appear in the API Console's UI. You can add more parameters and edit the summary/descriptions using the API Publisher UI as well. Once done, click Save.
Versioning the API
Let's create a new version of this API.
- Sign in to the API Publisher as
apicreator
if you are not logged in already. - Click the
PhoneVerification
API to open it and then click Create New Version.
Give a new version number (e.g., 2.0.0) and click Done.
Note that the new version of the API is created in the API Publisher.
Publishing the API
- Sign in to the API Publisher as the
apipublisher
user that you created earlier in this guide, and click thePhoneVerification
API's version 2.0.0.
- The API opens. Go to its Lifecycle tab and click Publish.
The check boxes mean the following:- Require re-subscription when publish the API: Invalidates current user subscriptions, forcing users to subscribe again.
- Deprecate old versions after publish the API: If selected, any prior versions of the API that are published will be set to the DEPRECATED state automatically.
- Require re-subscription when publish the API: Invalidates current user subscriptions, forcing users to subscribe again.
Go to the API Store (
https://<hostname>:9443/store)
using your browser and note that thePhoneVerification 2.0.0
API is visible under the APIs menu.
Subscribing to the API
Go to the API Store (
https://<hostname>:9443/store)
and create an account using the Sign-up link.
Fill the details of the Sign Up form appears and Click Sign Up.
After signing up, sign in to the API Store and click the
PhoneVerification 2.0.0
API that you published earlier.Note that you can now see the subscription options. Select the default application and the
Bronze
tier. Click Subscribe.- Once the subscription is successful, click View Subscriptions in the information message that appears to review your subscriptions.
Click the Production Keys tab of the application and then click Generate Keys to generate an access token that you use later to invoke the API. If you have already generated keys before, click Re-generate.
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
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.
Expand the GET method of the resource
CheckPhoneNumber
. Note the parameters that you added when creating the interactive documentation now appear with their descriptions so that as a subscriber, you know how to invoke this API.
Give sample values for the
PhoneNumber
andLicenseKey
and click Try it out to invoke the API.
Note the response for the API invocation. Since we used a valid phone number in this example, the response is valid.
You have invoked an API using the API Console.
Monitoring APIs and viewing statistics
Both the API publisher and store provide several statistical dashboards.
API Publisher statistics
API Store statistics
The steps below explain how to configure WSO2 API Manager Analytics with the API Manager. The statistics in these dashboards are based on data from WSO2 Data Analytics Server (DAS).
Let's do the configurations first.
Before you begin,
- Download the WSO2 APIM Analytics distribution. It is best to download and extract it to the same directory to which you downloaded WSO2 API Manager.
- If you have the API Manager server running, stop the server.
- If you are running on Windows, download the
snappy-java_1.1.1.7.jar
from here and copy the JAR file to the<ANALYTICS_HOME>\repository\components\lib
directory.
To enable Analytics, open the
<APIM_HOME>/repository/conf/api-manager.xml
file and set theEnabled
property under <Analytics>
totrue
as shown below. Save this change.<Enabled>true</Enabled>
Open the
<APIM_HOME>/repository/conf/log4j.properties
file. AddDAS_AGENT
to the end of thelog4j.rootLogger
property as shown in the example below.log4j.rootLogger=ERROR, CARBON_CONSOLE, CARBON_LOGFILE, CARBON_MEMORY, CARBON_SYS_LOG, ERROR_LOGFILE, DAS_AGENT
- Start the WSO2 APIM Analytics server, and then start the API Manager server. To start a WSO2 product server, navigate to the
<PRODUCT_HOME>/bin
directory in your console and run one of the following scripts as relevant.- On Windows:
wso2server.bat --run
On Linux/Mac OS:
sh wso2server.sh
- On Windows:
- Invoke several APIs to generate some statistical data and wait a few seconds.
- Connect to the API Publisher as a creator and click one of the statistical dashboards available in the Statistics menu. For example,
The Statistics menu is available for API creators and shows statistics of all APIs. Additionally, API creators can also see the following:
- Statistics of the APIs created by them by selecting the My APIs option in the drop down menu above each table or graph.
- The subscriptions of each API by clicking Manage Subscriptions.
- The alerts that can be configured for their APIs by clicking Manage Alert Types.
This concludes the API Manager quick start. You have set up the API Manager and gone through the basic use cases of the product. For more advanced use cases, see the Tutorials, User Guide and Admin Guide of the API Manager documentation.