Key Concepts

Let's take a look at some concepts and terminology that you need to know in order to follow the use cases.

API Manager components

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 the following high-level components:

API Publisher

API development is usually done by someone who understands the technical aspects of the API, interfaces, documentation, versions etc., while API management is typically carried out by someone who understands the business aspects of the APIs. In most business environments, API development is a responsibility that is distinct from API publication and management. 

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 https: //<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  https: //<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:

API Gateway

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.

Key Manager

Manages all clients, security and access token-related operations. The Gateway connects with the Key Manager to check the validity of OAuth tokens, subscriptions and API invocations. When a subscriber creates an application and generates an access token to the application using the API Store, the Store makes a call to the API Gateway, which in turn connects with the Key Manager to create an OAuth client and obtain an access token. Similarly, to validate a token, the API Gateway calls the Key Manager, which fetches and validates the token details from the database.

The Key Manager also provides a token API to generate OAuth tokens that can be accessed via the Gateway. All tokens used for validation are based on the OAuth 2.0.0 protocol. Secure authorization of APIs is provided by the OAuth 2.0 standard for key management. The API Gateway supports API authentication with OAuth 2.0, and enables IT organizations to enforce rate limits and throttling policies.

The Key Manager properly decouples the operations for creating OAuth applications and validating access tokens so that you can even plug in a third party-authorization server for key validations.

You can avoid making the Gateway connect with the Key Manager every time it receives an API invocation call, by enabling API Gateway caching. When caching is not enabled, a verification call happens every time the Gateway receives an API invocation call. For this verification, the Gateway passes an access token, the API, API version to the Key Manager. Communication between the API Gateway and the Key Manager happens in either of the following ways:  

• Through a Web service call
• Through a Thrift call (Thrift is the default communication protocol and is much faster than SOAP over HTTP)

If your setup has a cluster of multiple Key Manager nodes that are fronted by a load balancer that does not support Thrift, change the key management protocol from Thrift to WSClient using the <KeyValidatorClientType> element in the <APIM_HOME>/repository/conf/api-manager.xml file. Thrift uses TCP load balancing.

In a typical production environment, you can configure one of the following setups:

• Configure a WSO2 API Manager instance as the Key Manager in a separate server. See Product Profiles.
• Configure an instance of WSO2 Identity Server as the Key Manager. See Configuring WSO2 Identity Server as the Key Manager.
• Configure a third-party authorization server for key validations and an API Manager instance for the rest of the key management operations. See Configuring a Third-Party Key Manager.

Traffic Manager

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.

Handlers

When an API is created, a file with its synapse configuration is added to the API Gateway. You can find it in the<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.

Analytics

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  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.

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 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:

• CREATED: API metadata is added to the API Store, but it is not deployed in the API gateway and therefore, is not visible to subscribers in the API Store.
• 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 invoke the API without a subscription.
• PUBLISHED: The API is visible in the API Store and available for subscription.
• DEPRECATED: When an API is deprecated, new subscriptions are disabled. But the API is still deployed in the Gateway and is available at runtime to existing subscribers. Existing subscribers can continue to use it as usual until the API is retired.
• 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 a logical collection of APIs. An application is primarily used to decouple the consumer from the APIs. It allows you to :

• Generate and use a single key for multiple APIs
• Subscribe multiple times to a single API with different SLA levels

You subscribe to APIs through an application. Applications are available at different SLA levels, and have application-level throttling tiers engaged in them. A throttling tier determines the maximum number of calls you can make to an API during a given period of time.

The API Manager comes with a pre-created default application, which allows unlimited access by default. You can also create your own applications.

Callback URL

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.

• https://mytestapp.com/callback
• https://testapp:8000/callback

Your callback URL should have the following RegEx pattern.

regexp=(https://mytestapp.com/callback|https://testapp:8000/callback)

Access tokens

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 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

API visibility

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:

• API creator and publisher roles 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 Public.
• 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.

Subscription availability

The subscription availability option has three values as follows. You can set subscription availability to an API through the API Publisher's Manage tab. 

• Available to current Tenant Only: only users in the current organization/tenant domain can subscribe to the API 
• Available to All the Tenants: users of all organizations/tenant domains can subscribe to the API 
• Available to Specific Tenants: users of the organizations/tenant domains that you specify as well as the current tenant domain can subscribe to the API 

Subscription is available only to the current tenant in the following instances:

• When there is only one tenant in your system.
• Even if there are multiple tenants in your system, when you select Visible to my domain or Restricted by roles as the API's visibility in the previous step.

The diagram below depicts the relationship between the API's visibility and subscription availability:

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:

<APIPublisher>
   ....
   <EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels>
</APIPublisher>

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:

• Same as API visibility: Visible to the same user roles who can see the API. For example, if the API's visibility is public, its documentation is visible to all users.
• Visible to my domain: Visible to all registered users in the API's tenant domain.        
• Private: Visible only to the users who have permission to log in to the API Publisher Web interface and create and/or publish APIs to the API Store.

API resources

An API is made up of one or more resources, each of which handles a particular type of request. A resource has a set of methods that operate on it. The methods is analogous to a method or a function, and a resource is analogous to an object instance or a class in an object-oriented programming language. There are a few standard methods defined for a resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods.)

The diagram below shows a resource by the name CheckPhoneNumber added with four HTTP methods.

 When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.

<resource methods="POST GET" url-mapping="/state/town/*">
<resource methods="POST GET" uri-template="/{state}/{town}">

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 default in-sequence, out-sequence and fault sequences are generated when the API is published.

HTTP methods

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:

Cross-origin resource sharing

Cross-origin resource sharing  ( CORS ) is a mechanism that allows restricted resources (e.g., fonts, JavaScript) of a Web page to be requested from another domain outside the domain from which the resource originated.

The Swagger API Console that is integrated in the API Manager runs as a JavaScript client in the API Store and makes calls from the Store to the API Gateway. Therefore, if you have the API Store and Gateway running on different ports, enable CORS between them. 

The CORS configuration is in the <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample code.

<CORSConfiguration>
    <Enabled>true</Enabled>
    <Access-Control-Allow-Origin>https://localhost:9443,http://localhost:9763</Access-Control-Allow-Origin>
    <Access-Control-Allow-Methods>GET,PUT,POST,DELETE,PATCH,OPTIONS</Access-Control-Allow-Methods>
    <Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction</Access-Control-Allow-Headers>
    <Access-Control-Allow-Credentials>false</Access-Control-Allow-Credentials>
    </CORSConfiguration>

The elements are described below:

Change your code according to the sample given here.

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.

<handlers>
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler"/>
</handlers>

OAuth scopes

Scopes enable fine-grained access control to API resources based on user roles. 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.

How scopes work

To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API: 

Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.

Tom requests a token through the Token API as grant_type=password&username=tom&password=xxxx&scope=news_read news_write . However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API will be similar to the following:

"scope":"news_read","token_type":"bearer","expires_in":3299,
"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8"

Next, John requests a token as grant_type=password&username=john&password=john123&scope=news_read news_write . As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:

"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"4ca244fb321bd555bd3d555df39315",
"access_token":"42a377a0101877d1d9e29c5f30857e"

This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
   <ams:code>900910</ams:code>
      <ams:message>The access token does not allow you to access the requested resource</ams:message>
      <ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8
   </ams:description>
</ams:fault>

Applying a scope

You apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API > Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button under Resources.

On the screen that appears, enter a scope key, scope name and optionally, allowed roles and a description. Click Add Scope.

To apply the scope, you add the scope to a resource, save and publish the API.

Scope whitelisting

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 scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.

If you do not want a role validation for a scope in an API's request, add the scope under the <OAuthConfigurations> element in the <APIM_HOME>/repository/conf/api-manager.xml file and restart the server. It will be whitelisted. For example,

<ScopeWhitelist>
    <Scope>^device_.*</Scope>
    <Scope>somerandomscope</Scope>
</ScopeWhitelist>

Next, invoke the Token API to get a token for the scope that you just whitelisted. For example,

curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh" -H "Content-Type: application/x-www-form-urlencoded" https://10.100.0.3:8243/token

Note that the issued token has the scope you requested. You get the token without any role validation as the scope is whitelisted.

{"scope":"some_random_scope","token_type":"bearer","expires_in":3600,"refresh_token":"59e6676db0addca46e68991e44f2b8b8","access_token":"48855d444db883171c347fa21ba77e8"}

API templates

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.

Endpoints

An endpoint is a specific destination for a message such as an address, WSDL, a failover group, a load-balance group etc.

WSO2 API Manager has support for a range of different endpoint types, allowing the API Gateway to connect with advanced types of backends. It supports HTTP endpoints, URL endpoints (also termed as address endpoint), WSDL endpoints, Failover endpoints, Load-balanced endpoints. For more information about endpoints, see Working with Endpoints.

Sequences

The API Manager has a default mediation flow that is executed in each API invocation. There are 3 default sequences engaged as in, out and fault.

Caching

For information on configuring caching response messages and caching API calls at the Gateway and Key Manager server, see Configuring Caching.