Let's take a look at some concepts and terminology that you need to know in order to follow the use cases.
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
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:
...
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 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 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.
| Info |
|---|
Although the API Gateway contains ESB features, it is recommended not to use it for ESB-specific tasks. Use it only for Gateway functionality related to API invocations. For example, if you want to call external services like SAP, use a separate ESB cluster for that. |
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 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 Similarly, to validate a token, the API Gateway calls the Key Manager, which fetches and validates the token details from the databasedatabase.
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 When caching is not enabled, a verification a verification call happens every time the Gateway receives an API invocation call. For 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 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.
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.
...
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.
...
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., 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.
...
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 (registered and anonymous), 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.
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 in the system.
Given below is how visibility levels work for users in different roles:
- API
creatorandpublisherroles 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 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
Subscription availability
The subscription availability option has three values as follows. You You can set subscription availability to availability to an API through the API Publisher's Manage tab.
- Available to current Tenant Only: only only users in the current organization/tenant domain can subscribe to the API
- Available to All the Tenants: users users of all organizations/tenant domains can subscribe to the API
- Available to Specific Tenants: users users of the organizations/tenant domains that you specify as well as the current tenant domain can subscribe to the API 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 <AMthe <APIM_HOME>/repository/conf/api-manager.xml file, uncomment and set the following element to true:
| Code Block | ||
|---|---|---|
| ||
<APIPublisher> .... <EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels> </APIPublisher> |
Then, log in to the API Publisher, go to the Doc tab 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 is analogous to a method or a function, and a resource a resource is analogous to an object instance or a class in an objectclass in an object-oriented programming language. There are a 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 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.
| URL Pattern | A URL pattern can be one of the following types:
The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:
url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching. Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of Also see http://tools.ietf.org/html/rfc6570 on URI templates. |
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 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:
| OAuth scopes | You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. |
| Authentication type | 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. |
...
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 in the <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample code.
...
| XML Elements | Values | Description |
|---|---|---|
| <Enabled> | True/False | Used to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly. |
| <Access-Control-Allow-Origin> | HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 | The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly. |
| <Access-Control-Allow-Headers> | Header values you need to pass when invoking the API. For example, | Default values are sufficient for Swagger to function. |
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.
| Code Block | ||
|---|---|---|
| ||
<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.
...