A component is made up of one or more OSGi bundles. A bundle is the modularization unit in OSGi, similar to a JAR file in Java. The component-based architecture of all WSO2 products gives developers flexibility to remove or add features with minimum dependencies.
The API Manager comprises of the consists of the following high-level components:
WSO2 API Manager provides a simple Web interface called WSO2 API Publisher for API development and management. It is a structured GUI designed for API creators to develop, document, scale and version APIs, while also facilitating more API management-related tasks such as publishing API, monetization, analyzing statistics, and promoting.
The API Publisher URL is
//<YourHostName>:9443/publisher and it is accessible on HTTPS only. The default credentials are admin/admin.
The diagram below shows the common lifecycle activities of an API developer/manager:
API Store (Developer Portal)
The API Store Web application provides a collaborative interface for API publishers to host and advertise their APIs and for API consumers to self register, discover, evaluate, subscribe to and use secured, protected, authenticated APIs.
The API Store URL is
//<YourHostName>:9443/store and it is accessible on HTTPS only. The default credentials are admin/admin.
The diagram below shows common API consumer lifecycle activities:
A runtime, backend component (an API proxy) developed using WSO2 ESB. API Gateway secures, protects, manages, and scales API calls. It intercepts API requests, applies policies such as throttling and security using handlers and manages API statistics. Upon validation of a policy, the Gateway passes Web service calls to the actual backend. If the service call is a token request, the Gateway passes it directly to the Key Manager.
When the API Manager is running, you can access the Gateway using the URL https://localhost:9443/carbon. You integrate a monitoring and analytics component to the API Manager by configuring WSO2 API Manager Analytics. This component provides reports, statistics and graphs on the APIs deployed in WSO2 API Manager. You can then configure alerts to monitor these APIs and detect unusual activity, manage locations via geo location statistics and carry out detailed analysis of the logs.
The Traffic Manager helps users to regulate API traffic, make APIs and applications available to consumers at different service levels, and secure APIs against security attacks. The Traffic Manager features a dynamic throttling engine to process throttling policies in real-time, including rate limiting of API requests. For more information, see Working with Throttling.
When When an API is created, a file with its synapse configuration is added to the API Gateway. You can find it in thethe
<APIM_HOME>/repository/deployment/server/synapse-configs/default/api folder. It has a set of handlers, each of which is executed on the APIs in the same order they appear in the configuration. You find the default handlers in any API's Synapse definition.
For a detailed description of handlers and how to write a custom handler, see Writing Custom Handlers.
Additionally, monitoring and analytics are provided by the analytics component, WSO2 API Manager Analytics. This component provides a host of statistical graphs, an alerting mechanism on pre-determined events and a log analyzer. For more information, see Analytics.
Users and roles
The API Manager offers four distinct community roles that are applicable to most enterprises:
- Admin: The API management provider who hosts and manages the the API Gateway . S/he is responsible for creating user roles in the system, assign them roles, managing databases, security etc. The Admin role is available by default with credentials admin/admin.
- Creator: a creator is a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions 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. Creator can add APIs to the store but cannot manage their lifecycle.
- Publisher : a publisher manages a set of APIs across the enterprise or business unit and controls the API lifecycle, subscriptions and monetization aspects. The publisher is also interested in usage patterns for APIs and has access to all API statistics.
- Subscriber : a subscriber uses the API store to discover APIs, read the documentation and forums, rate/comment on the APIs, subscribes to APIs, obtain access tokens and invoke the APIs.
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.
The following stages are available in the default API lifecycle:
The API Manager comes with a pre-created default application, which allows unlimited access by default. You can also create your own applications.
A callback URL is a URL that sends a callback to a specific server or a program soon after your application request is sent. The callback URL is specified when generating or re-generating production or sandbox keys for an application. You can either provide a single application callback URL or a RegEx pattern as the callback URL. You should use a RegEx pattern as the callback URL when you need to specify multiple callback URLs for an applicable.
For example, in a situation where you have two (2) service providers that need to use the same application that have the following callback URLs.
Your callback URL should have the following RegEx pattern.
You can configure any RegEx pattern to match the callback URLs that you need to register with the application. However, it is mandatory have the prefix
An access token is a simple string that is passed as an HTTP header of a request. For example, "
Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a." Access tokens authenticate API users and applications, and ensure better security (e.g., certain types of prevent DoS attacks. Note that DoS attacks coming to key manager with random access tokens can not be prevented, and DoS attacks with same fake acess token can affect the gateway as well). If a token that is passed with a request is invalid, the request is discarded in the first stage of processing. Access tokens work equally well for SOAP and REST calls.
For more information about different types of access tokens and how to generate them, see Working with Access Tokens.
Throttling Throttling tiers
Throttling allows you to limit the number of successful hits to an API during a given period of time, typically in cases such as the following:
- To protect your APIs from common types of security attacks such as denial of service (DOS)
- To regulate traffic according to infrastructure availability
- To make an API, application or a resource available to a consumer at different levels of service, usually for monetization purpose
You can define throttling in the API, application and resource levels. The final request limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together. For more information about throttling, see Setting Throttling Limits.
API visibility and subscription Availability
Visibility settings prevent certain user roles from viewing and modifying APIs created by another user role.
- Public: The API is visible to all users (who are registered and anonymous (who use APIs without login), and can be advertised in multiple stores (central and non-WSO2 stores).
Restricted by Roles: The API is visible to it's tenant domain and only to the user roles that you specify. You should provide "roles" seperated by commas in UI or as curl parameter when calling REST API creating or editing the API.
Visible to my domain: The API is visible to all users who are registered to the API's tenant domain. This option is available only in a multi-tenanted environment. It's not applicable when there is only one active tenant (super tenant) in the system.
Given below is how visibility levels work for users in different roles:
publisherroles can see all APIs in their tenant store even if you restrict access to them. This is because those roles have permission to view and edit all APIs in the API Publisher, and therefore, does not have to be restricted in the Store.
- Anonymous users can only see APIs that have visibility as
- Registered users can see
- public APIs of all tenant domains
- all APIs in the registered user's tenant domain as long as the API is not restricted to a role that the user is assigned to
When using the REST API directly, these are the visibility options that you can specify public, private and restricted which analogus to the visiblity options specified in UI as below.
|API visiblity Level specified in UI||API visiblity Level specified in REST API|
|Public||public i.e. visibility=public|
|Visible to my domain||private i.e. visibility=private|
|Restricted by roles||restricted i.e. visibility=restricted&roles=role1,role2,role3|
The subscription availability option has three values as follows. You can set subscription availability to an API through the API Publisher's Manage tab.
The diagram below depicts the relationship between the API's visibility and subscription availability:
Refer the article Multi Tenant API Management with WSO2 API Manager for examples and real world usage of the above concepts.
API documentation visibility
By default, any document associated with an API has the same visibility level of the API. That is, if the API is public, its documentation is also visible to all users (registered and anonymous). To enable other visibility levels to the documentation, go to the
<APIM_HOME>/repository/conf/api-manager.xml file, uncomment and set the following element to true:
Then, log in to the API Publisher, go to the Docs tab of an API and click Add New Document to see a new drop-down list added to select visibility from:
You set visibility in the following ways:
The diagram below shows a resource by the name
CheckPhoneNumber added with four HTTP methods.
Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The diagram below shows the flow of a request sent to an API resource.
The default in-sequence, out-sequence and fault sequences are generated when the API is published.
HTTP methods specify the desired action to be performed on an API's resource. You can select multiple methods from GET, POST, PUT, DELETE, PATCH, HEAD and OPTIONS. A method has attributes such as an OAuth scope, authentication type, response content type, parameters etc. as the diagram below shows:
The main attributes of a method are described below:
You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method.
The authentication type can be one of the following:
Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. (The above screenshot shows this).
The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type.
|Response content type||You can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be.|
|Parameters||Parameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway.|
The elements are described below:
|Origin||Determines whether a resource can be shared with the resource of a given origin. The API Gateway validates the origin request header value against the list of origins defined under the Access Control Allow Origins configuration(this can be |
|response header in the response.||All Allow Origins(*), localhost|
|Headers||Determines, as part of the response to a preflight request (a request that checks to see if the CORS protocol is understood), which header field names can be used during the actual request. The gateway will set the header values defined under Access Control Allow Headers configurations.||authorization, Access-Control-Allow-Origin, Content-|
|Methods||This header specifies the method(s) allowed when accessing the resource in response to a preflight request. Required methods can be defined under the Access Control Allow Method configuration.||GET, PUT, POST, DELETE, PATCH, OPTIONS|
Change your code according to the sample given here.
|Credentials||Determines whether or not the response to the request can be exposed to the page. It can be exposed when the header value is true. The header value can be set to true/false by enabling/disabling the Access Control Allow Credentials configuration.||true, false|
If you try to invoke an API with inline endpoints, you add the CORS Handler in the
<handlers> section of the API's configuration as follows. Find the API's configuration in the
<APIM_HOME>/repository/deployment/server/synapse-configs/default/api folder.Change your code according to the sample given here.
<handlers> <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler"/> </handlers>
OAuth OAuth scopes
Scopes enable fine-grained access control to API resources based on user roles. You You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.
OAuth provides a method for clients to access a protected resource on behalf of a resource owner. OAuth 2 bearer token is a security token that any party in possession of it can use the token for authentication. Refer OAuth 2.0 Specification of Bearer Token Usage for more information.
How scopes work
To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API:
|Scope Key||A unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.|
|Scope Name||A human-readable name for the scope. It typically says what the scope does.|
The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.
To apply the scope, you add the scope to a resource, save and publish the API.
Tip: When you generate access tokens for applications with APIs protected by scope/s in the API Store, a Scopes drop down list is displayed in the the Production Keys tab of the application, where you can select the scope/s after the token is generated.
A scope is not always used for controlling access to a resource. You can also use it to simply mark an access token. There are scopes that cannot be associated to roles (e.g., openid, device_). Such Such scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.
An API template is its XML representation, which is saved in
<APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. This file comes with the API Manager by default. You can edit this default template to change the synapse configuration of all APIs that are created.
If you are using a distributed API Manager setup (i.e., Publisher, Store, Gateway and Key Manager components are running on separate JVMs), edit the template in the Publisher node.
An endpoint is a specific destination for a message such as an address, WSDL, a failover group, a load-balance group etc.
The API Manager has a default mediation flow that is executed in each API invocation. There are 3 default sequences engaged as
In-sequence is the first place that will be mediated through, once a request is dispatched to a resource of an API. At the end of the in-sequence the request can be forwarded to a back-end application for further processing.
Any responses coming from the back-end system are mediated through the out-sequence of the resource of the API.
Fault sequence is there to handle any errors that may occur while mediating a message through a resource.
When the sequence or the proxy service encounters an error during mediation or while forwarding a message, the message that triggered the error is delegated to the specified fault sequence. Using the available mediators it is possible to log the erroneous message, forward it to a special error-tracking service, and send a SOAP fault back to the client indicating the error. We need to configure the fault sequence with the correct error handling instead of simply dropping messages. For more information, see Error Handling.
For information on configuring caching response messages and caching API calls at the Gateway and Key Manager server, see Configuring Caching.