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 | ||||
|---|---|---|---|---|
|
...
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
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 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.
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 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
...
- 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 Lifecyclelife cycle in the API Publisher UI. - Go to the Lifecycle life cycle 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.
...