Introduction

This article describes briefly key functionalists and terms used in the WSO2 API Manager. In a distributed deployment of WSO2 API Manager we define a few server roles based on the task that each server carries out. Here I have briefly described what each server does and a few other API management related topics. While the WSO2 API Manager product includes everything you need: gateway, key manager, store, and publisher all embedded in a server, in production deployments, it's highly recommended to deploy them in a distributed manner. Here I have described common users and roles used in API management and also provided a brief introduction to tokens and security mechanisms used in the WSO2 API manager.

Applies To

Table of Contents

1. API Gateway
2. API Publisher
3. API Store
4. API Key Manager Server
5. Users and Roles
6. Conclusion
7. References

API Gateway

The API Gateway is responsible for securing, protecting, managing, and scaling API calls. It is a simple API proxy which intercepts API requests and applies policies such as throttling and security checks. It is also instrumental in gathering API usage statistics. We use a set of handlers for security validation and throttling purposes. It passes Web service calls to the actual back end after these validation steps - If the incoming web service call is a token request, the gateway directly passes it to the keymgt server to handle. We can add/remove these handlers using source view of the Synapse configuration. By default all security and throttling handlers will engage to each new API created by the Publisher. When it comes to production deployments this server hits the highest number of requests as all API calls goes through this server. We have to handle this situation very carefully. Fine tuning and additional configuration changes according to the environment is a must as we need to achieve optimum performance.

API Publisher

The API Publisher enables API providers to easily publish their APIs, share documentation, provision API keys, and gather feedback on APIs features, quality of service, and usage. You can create new APIs by pointing to actual back end service. Also we can define rate limiting policies available for that particular API. Here are the some of the API Publisher features.

Create, manage API and publish them to gateway.

Monitor API consumers, behavior, response time, last accessed time and etc.

List the active subscriptions per each API.

Manage life-cycles versions and policies. Based on the state of API you can set it to any of following state.

CREATED: API metadata has been added to API store, but it is not visible to subscribers yet, nor deployed to the API gateway

PUBLISHED: API is visible in API store, It will deploy in gateway if “Push to Gateway” option selected at Publishing time

DEPRECATED: API is still deployed into API gateway (available at run time 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 retired.

BLOCKED: Access is temporarily blocked.

API Store

The API Store provides a space for consumers to self-register, discover APIs functionality, subscribe to APIs, evaluate them and interact with API publishers. Here users can come and view existing APIs created and self sign in. After that they can create their own application by bundling multiple APIs together to one application. Once a user creates an application he can generate 3 types of keys used for authentication and security checks.

Application Token- This is a security token and we can use it to call APIs (bundled into application)

Consumer key and Consumer secret key- These key pairs can be used to generate a new access token for a given application and user.

Later we will see how we can use these keys to make an actual API call. Here is the feature list for the API Store.

View top used, new featured APIs and search by name, tag or creator.

API rate, share comments, feature requests and participate in forum discussions.

Create, manage applications, add/remove APIs to an application.

Generate application keys - consumer and consumer secret keys for applications. Re-generate new tokens if current tokens expire.

Download help and documents, contact business owners of API and ask questions.

Self-signup to API Store.

For API invocation we are use 2 types of keys. That is the Application Access Token and Application User Access Token. Based on the situation we can use each key. The following section will describe what each key does and how we can use them.

Application Access Token

API keys are generated by the API consumer and must be passed in the incoming API requests. We leveraged the OAuth2 standard to provide a simple, easy to use key management mechanism. The API key is a simple string, which must be passed as an HTTP header ( like this: "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a") and works equally well for SOAP and REST calls. API keys are generated at the application level and is valid for all APIs which are associated with this application. All access tokens have a fixed expiration time, which is by default set to 60 minutes. You can update this expiration time to a much longer time, such as several weeks ( FYI, 4 weeks is 2419200 seconds!). Consumers have the ability to re-generate the access token directly from the API store interface. The default expiration time can be changed by editing the Installation_root/repository/conf/identity.xml file and changing the value for AccessTokenDefaultValidityPeriod.

Application User Access Token

We also support the generation of access tokens on demand through a specific login API. In case of tokens expire, access tokens can be re-generate through this login API. For generation of access tokens, the login API takes 4 parameters:

Grant Type

Username

Password

Scope

Refresh Access Token

To generate a new access token, login API call should be issued with above parameters where grant_type=password. Then the login API returns two tokens; access token and refresh token. This returned access token is then stored in a session on the client side (the application does not need to manage users and passwords). On the API gateway, the access token is validated for each API call.

To refresh access tokens, login API takes 3 parameters:

Grant Type

Refresh Token

Scope

In case the token expires, the application will have to refresh a token by issuing the login call with above parameters where grant_type=refresh_token and refresh token should be the above generated refresh token value. The application concept is used to decouple the consumer from the APIs and allows 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 must create an application to subscribe to an API. The WSO2 API Manager comes out of the box with a Default Application and you can create as many applications as you need.Throttling Tiers can be applied to an Application as well as API level. API consumers can associate a throttling tier to an application which then defines the throttling limit for all the APIs subscribed under that Application.

API Key Manager Server

The API Key Manager Server is responsible for all security and key related operations. Normally when a gateway hits a API call it calls keymgt service and verifies the validity of the token provided. And if the Gateway gets a login call it directly forwards it to keymgt server. If we discuss a little bit about this login call it is basically used to get a new access token. So for this we have to pass username, password, consumer key and consumer secret key you got when you registered your application. All tokens used for validation are based on the OAuth 2.0.0 protocol. All secure authorization of APIs is provided using the OAuth 2.0.0 standard for key management. The API gateway supports API authentication with OAuth 2.0.0, and it enables IT organizations to enforce rate limits and throttling policies for APIs by consumer.

Users and Roles

There are four types of users we can consider in any API story. The roles are based on the privileges they have and tasks they perform.

Creator - The technical owner of an API

A creator will typically be a person in a technical role who understands the technical aspects of the API - interfaces, documentation, versions, how it will be exposed by API gateway, and uses the API publisher web application to provision APIs into the API store. The creator will use 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.

Publisher - The business owner of an API

The publisher typically manages a set of APIs across the enterprise or business unit and controls the API 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 - The developer or consumer of an API

The consumer uses the API store to discover APIs, consult the documentation and forums as well as rate/comments on the API. He/she subscribes to APIs to obtain an API key. Consumers can bundle multiple API’s together into one application and use it. Actual application consumers are user devices and it can be computer applications or mobile applications. See the diagram below to understand this concept clearly.

Administrator - The person who manages the entire API management system

Super administrator is responsible for defining new throttling rules, change existing rules, add new throttling policies manually into the system, add/or change uri template definitions, and create/manage all roles and users associated with the system. Basically this user managers the entire API management platform.

The following diagram depicts distributed deployment of WSO2 API Manager. You can see how each user (user role) and server is connected together.

Conclusion

The WSO2 API Manager is an open source API management product. We can deploy it in a distributed manner in production environments. We can also run the same API Manager server with different server roles according to the tasks they carry out. The WSO2 API manager supports clustering and can be scaled based on the API traffic.

References

1. WSO2 API Manager product home page

2. WSO2 API Manager Introduction - blog post

3. URL Template, URL Mapping and their usages in API Manager - blog post

Author

Sanjeewa Malalgoda, Software Engineer, WSO2 Inc.