Introducing WSO2 API Manager 3.2

Executive Summary

In the recent past, many enterprises have transformed digitally and have adopted API-driven business models to perform business activities. This has enabled them to enjoy the benefits of both digital transformation and modern API management.

APIs have become a major role player in today’s business world. The need for high-quality, feature-rich API management solutions have increased rapidly, and we now need these solutions to be on-premise, cloud, and containerized environments. Our product team has engineered WSO2 API Manager 3.2 to cater to these modern business requirements.

New Features in WSO2 API Manager 3.2

The latest version comes with a list of new major capabilities that significantly enhance and improve the user experience and workflows. Let’s take a look at some of the new capabilities.

Third-Party Key Manager Support

Prior versions only provided support for WSO2 Identity Server natively, and if a user wanted to connect a different IDP, they had to implement extensions and customizations. Also, utilizing multiple key managers at the same time required more customizations.

With WSO2 API Manager 3.2, we have simplified this process. Now, if an admin needs to incorporate a different identity provider to work with the product, they only have to configure the IDP using the admin console. Here, we require information about the IDP and credentials to access it.

Figure 1: Listing key managers

Once the key manager is defined in the admin portal, WSO2 API Manager is made aware of this key manager from that point onwards. When an API creator is creating an API, they can define what key managers defined with WSO2 API Manager can provide tokens to access this API.

Figure 2: Selecting key manager configurations

When a developer subscribes to this API, the relevant application can generate tokens from the relevant key manager to access the API.

Figure 3: Generating keys for an application

Introducing Approval Workflow Executor to API Manager

In previous versions, there were only two workflow executors: Simple Workflow Executor and WS Workflow Executor. The Simple Workflow Executor could be utilized in a simple scenario and the WS Workflow Executor was for approval or rejection processes, i.e., for tasks such as application creation and subscription through the Business Process Server (BPS).

For complex scenarios, having a BPS engine is useful; however, for simple approval and rejection tasks, this adds additional overhead (e.g.,, an additional server). Version 3.2 introduces the Approval Workflow Executor with an inbuilt workflow to perform simple approvals and rejections without the BPS.

The Approval Workflow Executor can be enabled for application creation, subscription creation, application key generation, user self sign up, and API state change. Approval workflow requests can be approved or rejected by the admin dashboard. Users can approve and reject workflow requests much more easily and without additional overhead.

Figure 4: The Approval Workflow Executor for application creation

API Publisher Test Console

WSO2 API Manager 3.2 offers a new feature to try out APIs from the publisher itself and verify functions and behaviors before publishing them to the gateway for subscribers. Only the developers (i.e., creators, publishers) are allowed to test the APIs through the test console. Developers can perform basic functional tests—such as mediation policies, make sure whether the request goes as expected to the back-end and the proper responses are received, request/response schema validation, and check whether the API resources are defined as expected.

The left pane test console of the publisher page can be used to select an operation to test. Once a user initiates the test by clicking on the initialize test button, the API is transformed to the prototype (testing) state and the swagger console is populated with a test-key (token), which prevents unauthorized users from accessing the API.

If the API is in the created lifecycle state, a developer can initialize the test to promote it to the prototype (testing) state. If a developer wants to test a published API, he or she has to initialize the test button to demote the API to the prototype (testing) state and test the API.

Figure 5: Initiating the test button

Once the test operation is initiated, the swagger console is populated as shown below.

Figure 6: Swagger console

The developer is given a test-key as shown in the below image to try out the API by clicking on Try It Out.

Figure 7: Try out console

GraphQL Query Complexity Analysis

With GraphQL queries, a client that requests data has more flexibility compared with REST and can request any amount of data. However, this flexibility comes at a cost; the GraphQL service might have to perform complex operations to serve each type of query it receives. To overcome this, the query should be analyzed before execution. Without protection to the backend, we could become vulnerable to DoS attacks (due to excessive load to the server, database, or network), which are caused by the execution of malicious and complex queries that are passed either intentionally or unintentionally.

Since clients can request highly complex queries, servers must be ready to handle them properly. WSO2 API Manager introduces the Static Query Analyser to secure GraphQL APIs to address such issues.

Also, to expose a GraphQL service as an API, a user can use this GraphQL Query Complexity as an alternative rate-limiting feature.

Figure 8: Depth of a GraphQL Query

OAuth 2.0 Endpoint Security

OAuth 2.0 is a widely used industry-standard delegation protocol for authorization and focuses on client developer simplicity while providing specific authorization flows for applications. OAuth 2.0 relies on SSL, which ensures that data remains in safe hands and that cryptography industry protocols are followed. Applications are allowed to access each other's data using tokenization without ever revealing the actual credentials of a user and therefore providing a strong authorization mechanism.

WSO2 API Manager now supports OAuth 2.0 Endpoint Security out-of-the-box. This means that APIs created in WSO2 API Manager can directly access OAuth 2.0-protected endpoints without any extension to WSO2 API Manager. Two of the four main grant-types declared in the OAuth specification are supported by this feature, namely the Client Credentials and Resource Owner Password grant types.

A Redis integration exclusive to the OAuth 2.0 Endpoint Security feature has also been introduced. This enables shared cache for token management in scenarios where a WSO2 API Manager deployment includes multiple API gateways.

Figure 9: Configuring endpoint security

Horizontal Pod Auto-Scaling with Custom-Metrics in the K8s API-Operator

The K8s API-Operator provides users with the opportunity to make their microservices highly available, with the ability to autoscale pods horizontally with custom metrics that they define. Both the APIs and backend microservices can be autoscaled with resource metrics such as CPU utilization, memory, and also with custom metrics. Sample custom metrics include http requests per second, response time, etc.

Users have to define a simple config map to define the targeted value of each metrics for the API and backend service. A sample scenario with detailed configurations can be found in the GitHub page of the K8s API-Operator.

Private Jet mode for Micro Gateways

With many applications gearing towards microservice architecture, it’s no surprise that container-orchestration systems such as Kubernetes have become so popular owing to features such as automating computer application deployment, scaling, and management, which simplifies a number of complex management tasks. WSO2 API Manager now provides cloud-native API management, where users can expose microservices as managed APIs in cloud environments with the support of the K8s API-Operator.

Microservices can be exposed as managed APIs in cloud clusters in private jet mode, where each microservice will have a dedicated API micro gateway. This will provide maximum security and guaranteed resource allocation for API execution. As depicted in the below diagram, when APIs published via WSO2 API Manager in cloud environments with private jet mode, deployment, scaling, and management tasks will be handled by the K8s API Operator itself.

Figure 10: Private Jet mode for micro gateway architecture

In order to deploy an API in a cloud environment, the environment configuration details should be added to the deployment.toml file or to the tenant-con.json files with respect to the user. Then, the added environment configurations can be selected in the environment tab in the publisher as shown below.

Figure 11: Cloud environments list

After saving the selected environment details, the API can be published in the selected environment by publishing the API from the lifecycle tab. This way, users can easily manage their APIs in cloud environments with WSO2 API Manager.

Gateway Runtime Artifact Synchronizer

Currently, in a multi gateway setup, synapse runtime artifacts, such as sequences, local entries, and endpoints are saved in <APIM_HOME>/repository/deployment/server/synapse-configs/default directory as XMLs and have to be synced between all the gateway nodes using NFS or rsync. When using NFS, we need to manage additional components that result in a considerable amount of changes in the current architecture. Thus, a solution without NFS to share the gateway runtime artifacts across the gateways has been introduced.

When an API gets published, edited, or removed, the synapse runtime artifacts corresponding to that API will be stored or updated in the extension point. Then, an event will be sent to Traffic Manager (TM) using event notifiers with the API name, UUID, and gateway label for the API. Gateways are subscribed to the TM. Gateway will filter out the events by the gateway label and APIs that have the gateway label will be sorted. Then, it will fetch the artifacts associated with the API from the storage (Database or GitHub) and load it to the memory. A New Gateway Rest API is introduced as a part of this feature to override the API deployment and retrieve the content of artifacts.

GIT Integration Support for API Controller

In today’s world, APIs have become important digital assets and enterprises are essentially building CI/CD pipelines for their APIs because they want to speed up the process of reaching the market. The API controller is at the heart of this process; it promotes the changes to the upper environments ensuring safety and reliability. The API Controller can now integrate with Git, which makes it easier to build your CI/CD pipelines in a simple but powerful manner.

From API Manager 3.2 onwards, the API Controller can operate on top of a Git repository and identify all the APIs/API Products and Application Projects that are committed to it. And it gives a single command to detect and deploy all the projects to the given environment. For example, it is possible to have any number of API projects in a single Git repository, and the API Controller can automatically detect those. If an API is updated, the API Controller will detect and migrate that particular API automatically.

Support for API Products from API Controller

WSO2 API Manager 3.2 offers support for API Products through WSO2 API Controller 3.2. Previous releases of WSO2 API Controller supported operations related to APIs and applications. But with this feature, the previous experience has been enhanced to API products as well, thus paving the way for the migration of API products to different environments while also assisting the CI/CD process.

An API product is a packaging mechanism that you can use when you need to bundle a preferred set of resources from multiple APIs and expose it as a separate API interface, which can be consumed by subscribers. This feature enables users to export, import, list, and delete API products and generate keys for API products using WSO2 API Controller 3.2.

Support for Different Endpoint Types from API Controller

WSO2 API Manager 3.2 offers support for different endpoint types through WSO2 API Controller 3.2. Even though WSO2 API Manager incorporates support for several endpoint types, the previous releases of WSO2 API Controller only supported HTTP/REST endpoints without the ability to choose the endpoint routing policy as load balancing or failover.

We now enable users to utilize not only HTTP/REST endpoints but also HTTP/SOAP endpoints with endpoint routing policies such as load balancing and failover. Also, this incorporates support for dynamic endpoints and AWS Lambda endpoints as well.

API Lifecycle Status Change Support

WSO2 API Controller 3.2 offers support to change the lifecycle status of an API. Although WSO2 API Manager provides the ability to change the lifecycle status of an API in the Publisher portal, WSO2 API Controller did not have direct support for this. Users were not able to change the API lifecycle status in the Controller itself using a single command. The only option was to update the API definition file to change the lifecycle status of an API and re-import it to reflect the changes.

API lifecycle status change support in WSO2 API Controller 3.2 provides users the ability to modify the lifecycle status of an API easily without accessing the Publisher UI. This feature would ideally fit in the automated CI/CD pipelines to meet the user requirements to update an API lifecycle status.

API/Application Delete Support for Controller

WSO2 API Controller provides support for API/Application deletion from 3.2 onwards. Even though WSO2 API Manager provided the ability to delete an API/application in the Publisher or Developer Portal, it did not have a controller command to meet this requirement.

WSO2 API Controller 3.2 provides the ability to delete an API/application using a single command, allowing users to easily remove an unwanted API or application in an environment without login into the Publisher or Developer Portal. This feature will be a noteworthy addition to the CI/CD processes when automating API/application-related operations.

API Key Authentication Support for API Operator

API key authentication support in API Operator provides a simple authentication scheme that accepts a valid self-contained JWT token issued for accessing APIs. The generated API key will be a self-contained JSON Web Token (JWT) that contains information about the user, subject, issuer, etc. The user is able to authenticate requests using an API key, on an API level or resource level.

First, the user will have to deploy security custom resource (CR) according to API key security-related configurations. A security CR created in the previous step should be referred to in the Swagger definition using a security extension. When an API refers to the Security CR in the definition under the security keyword, you need to make sure that the namespace of the security CR is the same as the namespace that the API belongs to. Then swagger definition will be deployed in the Kubernetes cluster as a managed API.

API Key Restriction for IP and Referrer

After issuing an API key for an application, it can be used by anyone to invoke an API subscribed to the application. However, if an unauthorized party obtains the token, this can lead to unnecessary invocations to the APIs. To prevent this, we can define the authorized parties when generating a token.

Figure 12: Generating an API Key to define allowed parties

WSO2 API Manager allows API keys to be restricted based on two approaches.

• IP address restriction

With this restriction, only clients with specific IP addresses can use the token. Users can either specify IP addresses explicitly or addresses as a range given in the CIDR notation, which makes it easier to restrict API keys to IP addresses in a subdomain.

• HTTP referer restriction

When the HTTP referer restriction has been enabled, only the specific HTTP referrers can use the token. Therefore, by using this restriction, when API clients run on web browsers, you can limit access to an API through only specific web pages.

Improvements in API Manager 3.2

The latest version of WSO2 API Manager has the following improvements in it.

Scope Management

Up until WSO2 API Manager 3.1.0, the Publisher Portal provided support for creating and managing scopes and attaching them to API resources. However, those scopes can only be created and used locally for each API, while only one local scope can be attached per API resource.

In some organizations, where multiple APIs are used by a single OAuth client, the role-based access control mechanisms of multiple resources across different APIs would be the same. When the number of OAuth clients accessing multiple APIs increases, each API resource scope should be updated with new scope bindings for each new OAuth client. When the number of APIs and scopes become large, this would become a tedious and time-consuming task for API developers/publishers to create scopes separately with unique scope keys while duplicating the scope-role bindings.

WSO2 API Manager 3.2 adds more improvements for this by supporting shared scopes per tenant and allowing multiple scopes to be attached to each API resource. The previous feature to create per API scopes locally will be deprecated from WSO2 API Manager 3.2 onwards. The new Publisher Portal provides a scope management UI to create, modify, and delete shared scopes. The same view allows the API developers/publishers to view the usages of each shared scope across the APIs in the same tenant. The management operations of shared scopes are protected using a separate REST API scope, so that only the privileged Publisher Portal users can define scopes that API developers can attach to their API resources later.

Figure 13: The shared scopes management view

The resources section of each API in the Publisher portal now provides support for attaching multiple scopes to each API resource, including combinations of both shared and per API scopes.

Figure 14: Attaching multiple scopes per resource

Revamped Admin Portal UI

WSO2 API Manager’s Admin Portal has been given a new and exciting look with the use of ReactJS, which is a popular JavaScript library for building user interfaces. The new Admin Portal UI clearly defines the administrative tasks that can be performed, and it also makes the workflows of API administrators simple and more efficient. It has a dashboard view that shows the summary of the administrative tasks and any pending workflow approvals. This makes it easier for administrators to keep track of pending or already-performed tasks. Just like the Publisher and Developer Portal, the Admin Portal is an OAuth2.0 client application, which authenticates to the WSO2 API Manager’s backend via Open ID Connect. Users now have the ability to customize and enhance the look and feel of the Admin Portal by extending the React components in the portal. The following images provide a glimpse of the new Admin Portal.

Figure 15: Admin Portal—Advanced Rate Limiting Policies

Figure 16: Admin Portal—Creating an Advanced Rate Limiting Policy

Accessibility Compliance of the Developer Portal

WSO2 API Manager’s Developer Portal now conforms to the Level A and Level AA Success Criteria of the conformance requirements of the Web Content Accessibility Guidelines 2.1 ( WCAG 2.1 ). This will make content more accessible to a wider range of people.

With this functionality, users can now operate through a keyboard interface. Color is not used as the only visual means of conveying information anymore. Content is now robust and understandable, making it more user friendly and easy to use.

Subscription Upgrade

The subscription tier upgrade feature will provide the capability to change the subscription tier of an already existing subscription without having to delete the subscription and resubscribing to the same API. In prior WSO2 API Manager releases, API consumers did not have the capability to upgrade their API subscription to a different tier. If they wanted a new subscription with a new tier, they had to delete the current subscription and re-subscribe to that relevant API with the new tier. The new release fixes this.

Once you have an active approved subscription, you can update the existing selected tier of the subscription as shown in the below image.

Figure 17: Updating the subscription tier

Also, developers have the option to enable an API subscription update approval workflow, which allows you to approve the throttling tier that the consumer has requested for the existing subscription. Admins can approve and set the new tier for the existing subscription. However, when an API subscription update workflow is enabled, when the consumer tries to update the tier of an active existing subscription to an API, it initially is in the `TIER_UPDATE_PENDING` state. The consumer can still use the API with the subscription with this state that still engages the previous existing tier, using its production or sandbox keys, until their subscription update to the new tier is approved. Once approval happens, the new requested tier will be assigned to the existing subscription with an 'UNBLOCKED' status and consumers can use the subscription that has the new requested tier.

In-Memory Subscription

Prior versions up to 3.1, query the database to validate the subscription when a request comes to the gateway node. When a request comes to the gateway, it calls the key manager node to validate the token and subscriptions by accessing the database. Based on the result, the request is forwarded to the backend.

As an improvement to this functionality, WSO2 API Manager 3.2 introduces in-memory subscription validation support to remove runtime dependencies between the gateway and the key manager node and validates the request by accessing the metadata in the in-memory data store. With this, WSO2 API Manager can serve the request even in a situation where the database is inaccessible.

Mock Response Payload Generation for API Prototyping

Mock Response Payload Generation has been improved to allow API publishers to generate complex inline scripts. This offers consumers the flexibility to obtain any response that is supported by a particular resource of the API.

Figure 18: A sample mock response

The script mediator is now capable of reading response codes and accept-header types while allowing API publishers to define multiple payloads under a single response code (e.g., 200 JSON and 200 XML), thus allowing consumers to obtain a specific response by providing the respective response code and accept-header type. This means that publishers and consumers no longer have to face the limitation of being able to define and retrieve only a single response per resource.

Support for Public Certificate Installation for Secure HTTP Communication for the Controller

WSO2 API Controller 3.2 offers support to import SSL certificates of WSO2 API Manager used in different environments. Certificates trusted by the operating system, which includes certificates of different Certificate Authority (CA), they will be imported by default. If there are any additional certificates needed for controller operations of different environments, they can be imported manually. Any DER or PEM encoded certificates can be imported after this improvement.

Improve Search for an API / Application in Controller

WSO2 API Controller 3.2 offers support to search APIs, applications, or API products during the listing process. They can be searched by name, version, provider, context, status, description, subcontext, doc, and label with -q or --query optional flag.

Try it out today!

It’s time to explore all these powerful features by yourself. Download the latest version of WSO2 API Manager and follow the official product documentation to get started. Moreover, you can find more resources on YouTube and Medium. If you want help from the community, head over to the slack channel. We have a global community there.