Through API Manager we can create our own web services such as REST, SOAP or even Websocket. What is more, with API Manager we are able to manage the full cycle of these web services in order to help us in their management, access policies or even monetization. But, when compared to similar products, another of its important features compared is its extensibility and customization.
We should also understand that API Manager is not carry out any logic operations. That is to say, the managed APIs are to be associated to a backend or an endpoint, They will be responsible for carrying our all logic operations associated with these APIs, which do not do or return anything on their own.
And that’s how it should be in most cases. Even if later, the reality of the productive environment always leads us to produce out-of-the-box solutions.
Concepts and Components in API Manager
To start with, it’s important to know that API Manager is divided into different components, each of which having a clearly-defined function. When combined, they form a product with multiple characteristics. These are the components:
- Analytics: Collection engine and statistics sampling.
- Publisher: API developer portal.
- Store: API consumer’s portal.
- Gateway: Requests and responses processor
- Key Manager: Access tokens manager
- Traffic Manager: Request traffic management.
However, we can customize many aspects of API Manager. It will be specifically in Getaway where we’ll be able to carry out API Manager extensibility or its customization when invoking APIs.
Thisis because the Gateway, which comes into play upon execution, is itself a component developed from the WSO2 ESB API. This will therefore enable, as we said before, the management all requests made to API Manager and the application of different use policies, both autonomously and through calls to other components (for example, traffic management rules, statistics generating, token control, request capture etc.)
Extensibility
The extensibility, as previously mentioned, is one of the most important characteristics of API Manager is its capacity to increase and customize its already wide variety of features. For the case in hand we are offered two possibilities: handlers and mediation flow. Each of them will be explained below.
- Handler: When an API is created, a configuration file is generated where all API-associated handlers are included. This set of handlers will be executed in the order indicated by the folder each time API is invoked. With custom handlers we can create a logic operation that will be executed in each generated API invocation.
- Mediation flow: Each API Manager call goes through an input sequence, sends the response back with an output sequence and, in case of an error, it is processed with a fault sequence. This is because requests are managed by the Gateway and its functioning is based on Proxy services.
These components, as we already know, are managed by the Gateway, which is responsible for intercepting and managing requests. But, in addition, we need to learn how and in which order they are invoked.
As we can see, the first ones to be executed are handlers, followed by our customized sequences and, lastly, the default sequences.
What are Handlers and What Actions do they Allow?
Handlers are interceptors of requests that have been made. They are associated with the API when it is created.
When we create an API, we generate a file which will be stored in the folder: <API-M_HOME>/repository/deployment/server/synapse-configs/default/api.
If we access a file in the folder we will see that its composition is identical to the ones of a WSO2 EI API. We will also be able to see how all handlers that already exist when it is created are associated.
By default there are several handlers that allow us to carry out the following actions:
- Setthe HTTP headers for CORS access control.
- Authentication control.
- Request throttling.
- Publish calls and answers latencies or API usage data only if Analytics is enabled.
- Call custom sequences if there are any set.
This file will look similar to:
<api xmlns="http://ws.apache.org/ns/synapse" name="admin--PizzaShackAPI"
context="/pizzashack/1.0.0" version="1.0.0" version-type="context">
<resource methods="DELETE PUT GET" uri-template="/order/{orderId}"
faultSequence="fault">
<inSequence>
<property name="api.ut.backendRequestTime"
expression="get-property('SYSTEM_TIME')"/>
<filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
<then>
<send><endpoint key="PizzaShackAPI--v1.0.0_APIproductionEndpoint"/><send>
</then>
<else>
<send><endpoint key="PizzaShackAPI--v1.0.0_APIsandboxEndpoint"/></send>
</else>
</filter>
</inSequence>
<outSequence>
<class name="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtResponseHandler"/>
<send/>
</outSequence>
</resource>
<handlers>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.common.APIMgtLatencyStatsHandler"/>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler">
<property name="apiImplementationType" value="ENDPOINT"/>
</handler>
// ...
</handlers>
</api>
As we have seen, we can modify our API’s behavior creating custom sequences that perform internal logic operations before or after a backend call. These sequences can be associated with a specific API or globally to all existing APIs.
Types of Custom Sequences
If we want to create them individually, we can associate them when we create an API from the Publisher’s portal. Through this portal we can create an API in three simple steps: design, implement and manage. It will be in the second step, implement, when we will indicate the backend endpoints and if we want to add an input, output- or fault-sequence. In order to do that, we must select the Enable Message Mediation check box and upload the sequence we want to associate using the buttons that will appear on screen.
By default, API Manager also counts several sequences that are freely available for developers. Which will allow us, among other things, to:
- Validate JSON or XML message format.
- Log a message.
- Keep the Accept header.
- Switch between XML and JSON or vice versa.
The setting we have just seen is only valid for the specific API in which it is set. API Manager also allows us to create a generic input sequence and/or output -sequence that will be executed in all APIs automatically. In order to do that we must create a sequence with a name that follows the scheme: WSO2AM–Ext–<address>. The address is In or Out. It can be added to the server folder:
<APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences.
Two things must be taken into consideration when creating files manually:
- The name of the file does not have to coincide with the name of the sequence.
- The sequence will not be seen in the Publisher’s selection combo box but it will be executed.
Conclusion
Through its different characteristics, API Manager allows us to increase logic operations associated with our APIs. In future posts we will see practical examples of how to execute these solutions.
