Key Concepts

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

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

Open

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:

Open

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 statistics component to the API Manager without any additional configuration effort. This monitoring component integrates with WSO2 Data Analytics Server, which can be deployed separately to analyze events. For more information, see Working with Statistics.

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

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.

Additionally, statistics are provided by the monitoring component, which integrates with WSO2 DAS.

The components are depicted in the diagram below:

Open

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.

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.

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.

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., prevent DoS attacks). 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.