About this Release

WSO2 API Manager is a complete platform for building, integrating, and exposing your digital services as managed APIs in the cloud, on-premise, and hybrid architectures to drive your digital transformation strategy. It allows API developers to design, publish, and manage the lifecycle of APIs and API product managers to create API products from one or more APIs. APIs can be built by integrating different types of APIs such as traditional request-response style APIs and Event-driven APIs using a low-code/no-code development experience, and the APIs can be exposed to consumers through its API Gateway.

For more information on WSO2 API Manager, see the overview.

The WSO2 API Manager 4.0.0 is the latest WSO2 API Manager release and is the successor of WSO2 API Manager 3.2.0 and WSO2 Enterprise Integrator 7.1.0. It contains the following components, which have new features and enhancements:

API Manager

The API Manager component addresses all aspects of API management in the platform. It consists of an API Gateway, API Publisher, Developer Portal, Key Manager, and Traffic Manager.

It is now available to download from here.

New features

  • New Service Catalog that lists registered services

    WSO2 API Manager includes a Service Catalog where developers can register their services in a RESTful manner. Service Catalog is one of the main attributes that enable the API-first Integration in WSO2 API Manager. Through the Service Catalog, integration services are made discoverable to the API Management layer so that API proxies can directly be created using them.

  • API and API Product revision support

    If you are an API Publisher, there can be a situation where you need to keep track of the different deployments of your API. For this purpose, a new concept named Revisions has been introduced. The revisions of your API can be deployed to specific Gateway Environment(s) as needed. You cannot edit the revisions. However, if required, you can restore your API to a specific revision if you want to discard the latest changes.

  • Support for ForgeRock Key Manager

    WSO2 API Manager can connect to ForgeRock out-of-the-box using the WSO2 API-M ForgeRock Connector. WSO2 API Manager has the capability to support multiple Key Managers at the same time. So with the use of connectors, it is capable of supporting any authorization server as a Key Manager, and in this case, it supports a connection to ForgeRock as a third-party Key Manager.

  • Support for PingFederate Key Manager

    WSO2 API Manager supports multiple Key Managers at the same time. As a result, WSO2 API Manager is prepacked with an inbuilt resident Key Manager, and with the use of connectors, it is capable of supporting any authorization server as a Key Manager. WSO2 API Manager can connect PingFederate out-of-the-box using the WSO2 API-M PingFederate Connector.

  • Support for Auth0 Key Manager

    It is possible to integrate the WSO2 API Manager with an external Identity and Access Management server (IAM) using the Auth0 OAuth Authorization Server to manage the OAuth clients and tokens that WSO2 API Manager requires. WSO2 API Manager has inbuilt support to consume APIs exposed by Auth0 OAuth.

  • Streaming API support in API Gateway

    Streaming APIs refer to APIs that have AsyncAPI definitions and use the WebSocket, WebSub (WebHook), and Server-Sent Events (SSE) protocols. Streaming APIs are popular in the Event-driven architecture (EDA). With Streaming APIs, you can expose and manage WebSocket, WebSub (WebHook), and Server-Sent Events backends in WSO2 API Manager. In WSO2 API Manager, Streaming APIs can be created by importing AsyncAPI definitions, and existing Streaming APIs can be exported as AsyncAPI definitions.

  • Exposing APIs via Custom Hostnames (Virtual Hosts)

    Virtual Host enables you to deploy an API or API Product Revision to a Gateway with a custom hostname. Gateway environments and its virtual hosts can be managed via the Admin Portal, and the API Publisher can choose a host when deploying an API Revision or API Product Revision.

  • TLSv1.3 support for API Gateway

    API Gateway supports TLSv1.3 protocol and can be enabled to provide a stronger transport-level security.

Deprecated features and functionalities

  • Message Tracing

    The support for this feature will be removed from subsequent versions starting from WSO2 API Manager 4.0.0.

Removed features and functionalities

  • Microgateway Labels

    Grouping APIs with Microgateway Labels is removed from this release. Instead, you can use Virtual Hosts (VHosts) and dynamically manageable Gateway environments to group and expose APIs with custom hostnames.

  • Implicit Grant

    Implicit Grant types have been removed due to security concerns.

  • Documentation content search

    Use the content search instead of the documentation content search (doc: keyword search) in the future.

Key changes

  • The name of the startup script has changed from wso2server.sh (Linux/Mac OS) and wso2server.bat (Windows) to api-manager.sh and api-manager.bat respectively. For instructions, see Running the Product.

  • The endpoints mentioned below previously worked through the Gateway. In API-M 4.0.0, WSO2 has moved them separately as follows:

    Until 3.2.0 In 4.0.0
    https://<gateway-host>/token https://<keymanager-host>/oauth2/token
    https://<gateway-host>/revoke https://<keymanager-host>/oauth2/revoke
    https://<gateway-host>/authorize https://<keymanager-host>/oauth2/authorize
    https://<gateway-host>/userInfo https://<keymanager-host>/oauth2/userInfo

  • Distributed setup profiles were refactored to three profiles from API Manager 4.0.0 and future releases.

    Profile Description Startup Argument
    Control Plane profile This profile contains the Publisher, Developer Portal, Key Manager, and Traffic Manager
    components.
    If you need to use the Traffic Manager profile separately, you need to disable
    the Traffic Manager component in the Control Plane profile.
    For more information, see API-M 4.0.0 distributed setup documentation.    		 -Dprofile=control-plane
    Gateway profile The API Gateway profile. -Dprofile=gateway
    Traffic Manager profile The Traffic Manager profile. -Dprofile=traffic-manager

  • API-related Synapse artifacts were moved from the file system to the in-memory. Therefore, there will not be any Synapse artifacts stored in the <API-M_HOME>/repository/deployment/server/synapse-configs/default/api directory. These Synapse artifacts are stored in the database and loaded to memory when the server starts up and when a new API revision is deployed and published.

    Expand to see how to retrieve the .xml files related to the existing artifacts

    Note that the instructions below should be followed to troubleshoot, in this scenario.

    • Add the configuration given below to the <API-M_HOME>/repository/deployment.toml file. 
      [synapse_properties]
'synapse.artifacts.file.storage.enabled' = true
    • Restart the server.
    • Check the <API-M_HOME>/repository/deployment/server/synapse-configs/default/api folder or any other synapse artifact, you will be able to notice that the xml files for the APIs have been created there.

  • With the inclusion of API revisioning it is required to have an API revision deployed in a Gateway to be able to publish an API.

Micro Integrator

The Micro Integrator is a cloud-native, standards-based messaging engine and an integration framework with a configuration-based runtime environment for integrating APIs, services, data, SaaS, proprietary, and legacy systems. This is a newly added component to WSO2 API Manager 4.0.0.

This serves the integration needs for the data plane of the API Manager platform.

It is now available to download from here.

New features

  • New and improved File Connector

    The File Connector allows you to connect to different file systems and perform various operations. The File Connector uses the Apache Commons VFS I/O functionalities to execute operations. For more information, see File Connector Example and File Connector Reference.

  • HashiCorp Secure Vault

    By default, the Micro Integrator is configured to use WSO2 secure vault for encrypting secrets. However, you may encounter certain limitations with WSO2 secure vault if you use secrets with a large number of characters. You can overcome this issue by using HashiCorp secrets.

  • JSON evaluation support for property mediator

    Enhanced JSON evaluation support was added for the property mediator.

  • FreeMarker support PayloadFactory mediator

    You can now use the FreeMarker template to write the payload. This is particularly useful when defining complex JSON payloads.

  • OAuth endpoint

    A message exit point or an endpoint defines an external destination for a message. Typically, this is the address of a proxy service that acts as the front-end to the actual service. You can configure the endpoint artifacts with any attributes or semantics needed for communicating with that service. An endpoint could represent a URL, a mailbox, a JMS queue, a TCP socket, etc., along with the settings needed for the connection.

  • Call mediator improvement

    Improvements have been made to the call mediator so that it can now store the response to a property.

  • Generating service catalog entry (open API definition)

    WSO2 API Manager includes a Service Catalog where developers can register their services in a RESTful manner. Integration services can be created when deploying your project as a C-App. These integration services are made discoverable to the API Management layer via the Service Catalog so that API proxies can directly be created using them.

  • Data Service Call Mediator

    Data Service Call mediator allows you to invoke data service operations from a mediation sequence without introducing an HTTP call (using the Call or Send mediators) to access the data service. This improves the server performance because the data service is accessed directly without going through the HTTP transport.

  • TLSv1.3 support for HTTP transport

    The HTTP transport has been improved to support TLSv1.3 protocol to provide a stronger transport-level security.

Compare this release with the Micro Integrator of WSO2 EI 7.x

The Micro Integrator is the integration runtime of WSO2 API-M 4.0.0 as well WSO2 EI 7.x versions.

The new features introduced with the Micro Integrator of API-M 4.0.0 are listed above. In addition, note the following significant changes:

  • The CLI tool of EI 7.x is replaced with the API Controller (CLI) of API-M 4.0.0.
  • The EI Kubernetes Operator of EI 7.x is merged with the API Operator of API-M 4.0.0.

Compare this release with previous ESBs

Given below is a comparison of the Micro Integrator of API-M 4.0.0 and the previous WSO2 ESB runtimes. Note that the Micro Integrator of API-M 4.0.0 is the latest, most improved version of the WSO2 ESB runtime.

If you are migrating from a previous ESB, this comparison will help you understand the important changes in the Micro Integrator that will impact your migration.

Note

The following comparison is applicable to the following versions of the WSO2 ESB runtime:

Feature comparison

The following table explains the availability of the most critical features in the ESB runtime and Micro Integrator runtime of API-M 4.0.0. In addition to the following list, the Micro Integrator runtime also contains new and improved features listed above.

WSO2 ESB Runtime Micro Integrator Runtime
Startup time 40s 5s
Distribution size ~600 MB ~150 MB
Product configuration model XML-based configurations TOML-based configurations
Mediation (ESB) features Available Available
Data Integration features Available Available
Task coordination Hazelcast based RDBMS based
Tooling WSO2 Integration Studio WSO2 Integration Studio
Runtime monitoring and management Management Console Micro Integrator Dashboard
API Controller (CLI)
CAR Deployment Available Available
Registry RDBMS-based Registry File system based Registry
Hot deployment Available Available

Removed Features

The following features, which are available in ESB runtimes, are removed from the Micro Integrator of API-M 4.0.0 because they are not frequently used.

Feature Description Alternative
Management Console WSO2 Integration Studio is the recommended tool for developing integration solutions. The monitoring capabilities available in the management console (of the ESB profile) are available through the new Micro Integrator dashboard. Micro Integrator Dashboard
Multitenancy This is not a widely used feature in the ESB profile. Multitenancy does not suit the world of microservices or micro integrations. -
SVN-based DepSync This is not a widely used feature in the ESB profile, and is not recommended for use. Third-party offering like Rsync
RDBMS-based Registry - File system based Registry
Rule Mediator The rule mediator has been removed as it is not widely used. -
HL7 Message Store In previous ESBs, an HL7 Message Store could be configured using the custom message store implementation. Due to limited capabilities and tight coupling with the Hl7 console (which was previously available in the management console), this functionality is not available in API-M 4.0.0. -

Mediators and artifacts removed (After ESB 5.0.0)

The following mediators and artifacts are removed from the ESB runtime in all versions after ESB 5.0.0. If you are migrating from ESB 5.0.0 to the Micro Integrator of API-M 4.0.0, note that these artifacts are no longer supported.

  • Priority Executors
  • Enqueue Mediator
  • Bean Mediator
  • POJO Command Mediator
  • Spring Mediator
  • Conditional Router Mediator
  • In, Out Mediators
  • Event Mediator
  • In memory Topics
  • Router Mediator
  • Publish Event Mediator

Streaming Integrator

Streaming Integrator serves the streaming-based integrations and acts as the event stream provider for Streaming APIs in the data plane of the API Manager platform. This is a newly added component into WSO2 API Manager 4.0.0.

It is now available to download from here.

New features

  • Deploy AsyncAPI definitions to WSO2 API-M Services

    WSO2 Streaming Integrator has the inbuilt capability to directly deploy Siddhi applications with Async API definitions to WSO2 API Manager services. These services can then be used to create an API and deploy in the API Manager runtime.

  • SSE Sink / Source support over HTTP

    SSE is an HTTP-based protocol that allows one-way communication (similar to WebHooks) from the server to the client. For more information, see SSE Server Sink and SSE Source.

  • WebSub Sink / Source support over HTTP

    Above Source and Sink implementation are based on the WebSub protocol specification. WebSubs only allows one-way communication, from a caller web app to a callee web app. For more information , see WebSub Sink , WebSub Source.

  • Improved MongoDB Store

    Several improvements are done, such as making the encryption protocol configurable, Object_ID support when searching specific values in the store, and other bug fixes. For more information, see Mongo DB Store.

  • Improved IO CDC Source

    CDC(Change Data Capture) can be used to capture insert /update/delete actions from databases. With the new improvements, you can handle all three actions using a single CDC configuration. For more information, see CDC Source.

  • Synchronous publishing support for IO Kafka

    IO Kafka allows seamless connection with the Kafka broker and retrieves the events into the Streaming Integrator. This release includes synchronous publishing of events, which allows more controlled event publishing and other bug fixes. For more information, see IO-Kafka.

  • Improved JSON Mapper to support null values

    JSON mapper provides capability to retrieve or publish events in JSON format. Release contains improvement where when null values arrives into the system they are treated as null values if needed. For more information , see Map-JSON.

  • Improved KeyValue Mapper to support force casting

    The KeyValue mapper allows the Streaming Integrator to get events and publish events as a key-value pair. For more information, see Map-KeyValue.

  • Improved IO File Sink and Source

    IO File sink/source is used to read or write into a file. With the new improvements, the Streaming Integrator supports EOF(End Of File) in other modes, file trailers, file-writing mechanisms, and SFTP. For more information, see IO-File.

  • Improved Store RDBMS support

    Store RDBMS can be used to connect with any RDBMS type. With the new versions, it supports adding null values to RDBMS tables and includes improved metrics support. For more information, see Store RDBMS.

  • Kafka and HTTP metrics monitoring

    This release provides Kafka and HTTP metrics monitoring capability. In the previous release, this was only available for File, RDBMS and CDC (Change Data Capture). The metrics can be published to a preconfigured Prometheus server and then you can either create your own Grafana dashboard or use the ETL dashboard which is already created by us. For more information on how to configure metrics, refer to Monitoring ETL Flows documentation page.

API Controller (apictl)

WSO2 API Controller (apictl) is a command-line tool providing the capability to move APIs, API Products, and Applications across environments and to perform CI/CD operations. It can also be used to perform these same tasks on a Kubernetes deployment. In addition, apictl can be used as a developer CLI tool for Choreo Connect. Furthermore, it can perform Micro Integrator server-specific operations such as monitoring Synapse artifacts and performing MI management/administrative tasks from the command line.

It is now available to download from here.

New features

WSO2 Integration Studio

WSO2 Integration Studio is an open-source development environment used to design and develop integration scenarios for WSO2 Micro Integrator.

It is now available to download from here.

New features

  • PayloadFactory mediator supports FreeMarker templates
  • Enrich mediator improvements
  • OAuth feature for HTTP endpoints
  • Dynamic endpoint support for mock services in synapse unit testing
  • Call mediator improvements
  • Parent maven details included in the children POM by default
  • Kubernetes exporter project is enhanced to support a pure Kubernetes deployment
  • Apply software updates to the embedded Micro Integrator runtime
  • OpenAPI specification 3.0 support
  • Publish integrations to the API-M runtime during deployment
  • Cassandra datasource support for data services
  • Adding Registry Resource Properties

Key changes

  • The folder structure of the ESB Configs modules is changed to include the Swagger-related metadata in the /resources directory.
  • WSO2 Integration Studio now supports OpenAPI specification 3.0 by default.
  • Use a new workspace for WSO2 Integration Studio 8.0.0 and import any existing projects (created using older Integration Studio versions) into this new workspace.

Micro Integrator Dashboard

The Micro Integrator dashboard can connect to multiple Micro Integrator server instances and monitor artifacts and logs from a selected cluster or group of server nodes.

It is now available to download from here.

New features

  • Revamped dashboard, which can monitor multiple Micro Integrator instances grouped together

Streaming Integrator Tooling

The Streaming Integrator Tooling is a developer tool to develop Siddhi applications and simulate events for testing purposes.

It is now available to download from here.

New features

  • Async API View

    This release introduces a new 'Async API' view in addition to the existing 'Source/Design' views and 'Wizard' view.

    Using the Async API View, you can generate an Async API specification for a given Siddhi app.

    The following sinks/sources can be exposed as an Async API : WebSocket server (sink), web socket-server (source), WebSocket (source), SSE server (sink), WebSubHub (source)

    See the example use case.

  • Tooling support for WebSubHub Source and WebSubHub Sink

    Tooling support is added for the newly introduced WebSubHub source and WebSubHub sink. For details, see the Streaming Integrator - New Features section above.

  • Tooling support for SSE Source and SSE-server Sink

    Tooling support is added for the newly introduced SSE Source and SSE-server Sink. For details, see the Streaming Integrator - New Features section above.

  • Siddhi Error Replay for 'Store' type errors

    This release enables error replay for database connection errors. Errors that occur during ADD, DELETE, UPDATE, ADDORUPDATE operations can be replayed from the Error Store explorer.

    See the tutorial on handling store-type errors.

Choreo Connect

The Choreo Connect is a lightweight gateway for APIs. It is used for message security, transport security, routing, and other common API Management related quality of services. It can collect information required for usage metering and throttling capabilities. The Choreo Connect natively supports scaling in highly decentralized environments including microservice architecture.

WSO2 API Manager 4.0.0 is compatible with Choreo Connect 1.0.0.

New features

Please see the supported features

Kubernetes API Operator

Microservices are increasingly being deployed on Kubernetes. As a result, it is important to expose these microservices as well documented, easy to consume, managed APIs so that they can be used to develop great applications. The API operator for Kubernetes makes APIs a first-class citizen in the Kubernetes ecosystem. Similar to deploying microservices, you can now use this operator to deploy APIs for individual microservices or compose several microservices into individual APIs. With this, users can expose their microservice as managed APIs in the Kubernetes environment without any additional work.

The API operator for Kubernetes provides first-class support for Micro Integrator deployments in the Kubernetes ecosystem. It uses the Integration custom resource (integration_cr.yaml file) that is available in the Kubernetes project (exported from WSO2 Integration Studio) and deploys the integration in your Kubernetes environment.

It is now available to download from here. K8s API Operator v2.0.0 is compatible with API Manager v4.0.0.

New features

  • Deploy APIs to API Manager
  • Deploy Integrations with Micro Integrator

Compatible WSO2 product versions

WSO2 API Manager 4.0.0 is based on WSO2 Carbon 4.6.1 and is expected to be compatible with any of the WSO2 products that are based on any Carbon 4.6.x version. If you encounter any compatibility issues, please contact team WSO2. For more information on the products in each Carbon platform release, see the Release Matrix.

Fixed and known issues

API Manager

Micro Integrator

Streaming Integrator

API Controller

Integration Studio

Micro Integrator Dashboard

Streaming Integrator Tooling

Choreo Connect

Kubernetes API Operator

What has changed

WSO2 API Manager Server 4.0.0 brings a range of new features and major improvements. The following aspects have changed in 4.0.0 compared to the previous WSO2 API-M versions. This page provides details about those behavioral changes.

  • Prior to WSO2 API Manager 4.0.0, the distributed deployment consisted of five main product profiles, namely Publisher, Developer Portal, Gateway, Key Manager, and Traffic Manager. However, the new architecture in API-M 4.0.0 only has three profiles, namely Gateway, Traffic Manager, and Control Plane.

  • From API-M 4.0.0 onwards, API Manager offers analytics as a cloud service.

    If you are using Analytics

    As the on-premise analytics data cannot be migrated to the Cloud, you need to maintain the old analytics server and keep the UI running for as long as you need that data (e.g. 3 months) after migrating to the new version of analytics in WSO2 API-M 4.0.0.

  • From API-M 4.0.0, server startup script has renamed as api-manager.sh (for Linux) and api-manager.bat (for Windows)

  • From API-M 4.0.0 onwards, synapse artifacts have been removed from the file system and are managed via database. At server startup the synapse configs are loaded to the memory from the Traffic Manager.

  • Token and Revoke endpoints have been removed from the Gateway artifacts from API-M 4.0.0 onwards. Use endpoints in the Control Plane instead.

    3.2.0 

    https://localhost:8243/token
https://localhost:8243/revoke

    4.0.0 

    https://localhost:9443/oauth2/token
https://localhost:9443/oauth2/revoke

  • All the data is persisted in databases from WSO2 API-M 4.0.0 onwards. Therefore, it is recommended to execute the migration client in the Control Plane profile.

  • From API-M 4.0.0, the kid claim has been removed from the backend JWT. If there are customizations that require validating the kid value of the backend JWT, please customize the JWT generator to include kid value.

  • From API-M 4.0.0 onwards Other '_overview' type documents override the API description, if you had created such documents in your lower environments, please note that those documents will not be displayed in document listing page. You can edit those documents the same way you edit the API description.

  • Token and Revoke endpoints has been removed from the gateway artifacts from API-M 4.0.0 onwards. Use endpoints in the control plane instead.

  • From WSO2 API_M 4.0.0 onwards error responses in API calls has changed from XML to JSON format.

If you have developed client applications to handle XML error responses

If you have developed client applications to handle XML error responses you have to change the client applications to handle the JSON responses. As an example for a 404 error response previously it was as follows

    <am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>404</am:code>
    <am:type>Status report</am:type>
    <am:message>Not Found</am:message>
    <am:description>The requested resource is not available.</am:description>
    </am:fault>

In API-M 4.0.0 onwards the above resopnse will changed as follows.

{
"code":"404",
"type":"Status report",
"message":"Not Found",
"description":"The requested resource is not available."
}

As an example for a 404 error response previously it was as follows

    <am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>404</am:code>
    <am:type>Status report</am:type>
    <am:message>Not Found</am:message>
    <am:description>The requested resource is not available.</am:description>
    </am:fault>

In API-M 4.0.0 onwards the above resopnse will changed as follows.

{
"code":"404",
"type":"Status report",
"message":"Not Found",
"description":"The requested resource is not available."
}

Important

From WSO2 API_M 4.0.0 onwards, the following fault sequences were changed to send JSON responses as mentioned above. If you have done any custom changes to any of the following sequences previously, you have to add those custom changes manually to these changed files.

  • auth_failure_handler.xml
  • backend_failure_handler.xml
  • block_api_handler.xml
  • graphql_failure_handler.xml
  • threat_fault.xml
  • throttle_out_handler.xml
  • token_fault.xml
  • fault.xml
  • main.xml
Top