WSO2 API Manager Quickstart

The API Management Connector can be easily integrated with WSO2 API Management version 4.1.0 (and above).

This quick start walks through the prerequisites, describes the initial configuration of the Connector and WSO2 API Management and provides a walkthrough of the API life cycle in WSO2 API Management.

Prerequisite - Getting Started with PubSub+ Cloud

To get started with PubSub+ Cloud, you can use a trial account. The sections below provide an overview and the Solace Doc site contains more detailed information to get started.

Accessing PubSub+ Cloud

Before You Begin

Before you begin, you require an email address to register your trial account (see below).

To use PubSub+ Cloud, you require a supported web browser. For a list of supported browsers, see Supported Web Browsers.

Creating a Free Trial Account

If you don't have a Solace Cloud Account yet, you can sign up for a Free Trial PubSub+ Cloud account via a web browser; otherwise, use your account to login using the steps in the following section. The Free Trial account is sufficient for this and the other tutorials in this help, but you can use a Starter, Professional, or Enterprise account as well.

In your browser, visit the New Account page, enter the requested information, and you'll be logged into the PubSub+ Cloud.

Logging in to the PubSub+Cloud Console

To start using PubSub+ Cloud, log in to the PubSub+Cloud Console. From there take a look around to familiarize yourself with the interface:

If you aren't logged into PubSub+ Cloud, in a browser, go to the PubSub+ Cloud login page at https://console.solace.cloud/login.
Enter in your email and password that you used when you signed up and then click Sign in.
You should now be logged in to the PubSub+Cloud Console.
Take a tour of the Cloud Console if it's your first time.

Tour of the PubSub+Cloud Console

Before you start your journey to learn about PubSub+ Cloud, let's take a tour of the Cloud Console.

The first page is the Welcome page that shows the tools that you can use, based on the roles that you're assigned. On the left, is a navigation bar that remains static so that you can jump from tool to tool as required.

If you are on a trial, on the Welcome page, the top-right corner shows the number days left in your trial.

The PubSub+Cloud Console is the interface for you to access the PubSub+ Cloud services for event streaming.

To access these services, you can select the tool from the navigation bar or click a card on the Welcome page.

To manage event streaming, you use Mission Control that provides the following tools:

Cluster Manager: You use this tool create, configure, and manage event broker services. For more information, see Cluster Manager.
MeshManager: You use this tool to visualize and connect your event broker services. For more information, see MeshManager (Beta).

The following illustration shows where Mission Control is located and where you can select Cluster Manager and MeshManager:

To learn more about the other capabilities provided in Solace Cloud see Tour of the PubSub+ Cloud Console on the Solace Docs site.

Creating your Event Broker Service

After you have logged into the PubSub+Cloud Console, you'll see a welcome page with a navigation bar on the left-hand side of the page:

On the navigation bar, is Mission Control. It allows you create and configure event streaming. In particular, you use Cluster Manager to create and manage your event broker service. When you launch Cluster Manager, you go to the Services page. This page shows you the event broker services that are available to you. If this your first service on the account, there won't be any services. Follow these steps to create your event broker service:

If you aren't logged into PubSub+ Cloud, in a browser, go to the PubSub+ Cloud login page.
In the PubSub+Cloud Console, on the navigation bar, select Cluster Manager .
On the Services page, click the Create Service button located on the top right corner of the page or click the Create Service card.
In the Select Service Type step, select the type of service to use.

For your first event broker service, select any available service type. PubSub+ Cloud offers service types that provide various levels of messaging performance. Some of these service types may be inaccessible before configuring a billing method for your account. You can request access to additional service types later. If you have a trial account, you will only have access to one Developer service. For now, select Developer.
In the Select Cloud step, select a cloud provider from the drop-down menu. For example, select Amazon Web Services.
In the Select Region step, choose where the you want the service to run. To do this, click the map and choose a region for the provider you selected, and then click OK. For your first event broker service, choose the region closest to your geographical location. For example, choose Canada Central (Montreal).
In the Service Details step, do the following:
- Leave the default version in the Select Your Broker Version drop-down.
- Enter a name for the event broker service in the Service Name field. An event broker service is identified by its name.
Click Start Service to create your first event broker service.

You've now created your event broker service!

Creating an API Token

To connect your APIM-Connector to Solace Cloud, you need an API token as the connector utilises the Solace Cloud REST API.

To get an API token, you must generate it in the PubSub+ Cloud Console. You generate and manage API tokens at an account level and also configure the permissions it has (i.e., a subset of the permissions you have when you log in to the PubSub+ Cloud)

Before you can start managing APItoken for using the PubSub+ Cloud RESTAPIs, you require the following:

A PubSub+ Cloud account.
A role assigned that allows you create an APItoken and assign the proper permissions to that APItoken. In the steps below, we show the permissions available for assigning if your account had the Administrator role.

The following steps show you how to create an API token that has the permissions to use a majority of the PubSub+ Cloud REST API, Event Portal REST API, and event broker service REST API. It's important to note that after you create the APItoken, you cannot modify a token's permissions. If you require updated permissions, you must create another token.

You can use the following steps to create an API token:

Log in to PubSub+ Cloud. If you belong to multiple accounts (or Workspaces), select the account you want to create anAPItoken for when prompted after logging in.
At the bottom of the left-hand menu, click the user icon, and then click Token Management.
In the top-right corner, click the Create Token button.
On the Create Token page, in the Token Name box, type a unique name for the API token.
On the Select Permissions section, click the toggle beside the permission you want to enable .

Please enable the permissions for the following endpoints:

My Service, Organization Services
Event Portal -> Designer Read
Event Portal -> Event API Products Read

Deploying the API Management Connector

The Connector consists of multiple docker containers. The minimum deployment consists of the Connector Server and Mongo DB for data storage. We provide a simple docker compose template that also deploys a demo API Management portal for Async APIs that is useful for debugging and prototype/POC activities.

Environment Variables

For the docker deployment you'll need an environment file and we provide a sample environment configuration file.

The core variables required by the connector are documented here.

Docker based Deployment

The sample docker template sets up all components of the API-Management Connector using docker-compose:

Connector Services
Database Backend - Mongodb
Sample/Demo Portal Application
Nginx as reverse proxy

The README of the simple docker template contains more detailed information on the files that are part of the template:

Preparing the API Management Connector

An initial configuration of the Connector must be carried out using its REST API:

Setting up an Organization
Setting up an Environment
Setting up a generic developer (TODO - streamline)

The Connector's REST API is documented using Open API and you can explore the API by browsing to http://{connector_host}:{connector_port}/api-explorer.

Conventions

The API call examples below use curl.

The following place holders are used in the cURL commands, you need to replace these with the correct values:

{connector_host}: host name or IP of the connector server
{connector_port}: port of the connector server
{org_admin_name}: user name of a user with org-admin privileges
{org_admin_pwd}: password of the user with org-admin privileges
{org_name}: name of the organisation/tenant you want to create

Set up an organisation (tenant) in the connector

In order to create an organisation the call must be made using credentials of a user with platform-admin privileges. (refer back to the deployment section which outlines how the users are configured).

In the call below you need to replace the following (in addition to the common placeholders documented above):

{connector_admin_name}: user name of a user with platform-admin privileges
{connector_admin_pwd}: password of the user with platform-admin privileges
{cloud_token}: an API token for Solace Cloud - see above for how to create this token
{org_name}: the name of the tenant you want to create. Note: remember the org_name as you need it to configure the WSO2 API Management

curl --location --request POST 'http://{connector_host}:{connector_port}/v1/organizations' \
--user {connector_admin_name}:{connector_admin_pwd}> \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "{org_name}",
  "cloud-token": "{cloud_token}"
}'

Create an environment - register a PubSub+ broker as an API gateway

{service_id}: the id of a PubSub+ broker in your Solace Cloud account. You can use the first cURL command below to retrieve a list of available services and their service ids.
if required adjust the protocols in the request - the Connector verifies that these protocols are enabled on the service you specify with {service_id}

Retrieve services in the associated Solace Cloud account:

curl 'http://localhost:9090/v1/my-org/services' \
--user {org_admin_name}:{org_admin_pwd}>

Locate the service you want to use for your environment in the response and take note of its serviceId, you need it in the payload of the next call to create an environment.

Also take note of the endpoint URIs for ws-mqtt, wss-mqtt, http and https. See this partial example response of the REST call (the actual response may contain more protocols):

    "messagingProtocols": [
      {
        "compressed": "no",
        "secure": "no",
        "protocol": {
          "name": "ws-mqtt",
          "version": "3.1.1"
        },
        "transport": "WS",
        "uri": "ws://{service_id}.messaging.solace.cloud:8000"
      },
      {
        "compressed": "no",
        "secure": "yes",
        "protocol": {
          "name": "wss-mqtt",
          "version": "3.1.1"
        },
        "transport": "WSS",
        "uri": "wss://{service_id}.messaging.solace.cloud:8443"
      },
      {
        "compressed": "no",
        "secure": "no",
        "protocol": {
          "name": "http",
          "version": "1.1"
        },
        "transport": "HTTP",
        "uri": "http://{service_id}.messaging.solace.cloud:9000"
      },
      {
        "compressed": "no",
        "secure": "yes",
        "protocol": {
          "name": "https",
          "version": "1.1"
        },
        "transport": "HTTPS",
        "uri": "https://{service_id}.messaging.solace.cloud:9443"
      }
    ],

Create an Environment:

curl --location --request POST 'http://{connector_host}:{connector_port}/v1/{org_name}/environments' \
--user {org_admin_name}:{org_admin_pwd}> \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "dev",
  "displayName": "dev display name",
  "description": "dev environment",
  "serviceId": "{service_id}",
  "exposedProtocols": [
    {
      "name": "secure-mqtt",
      "version": "3.1.1"
    },
    {
      "name": "https",
      "version": "1.1"
    }
  ]
}'

Note: Remember the environment name

Create a developer

Next let's create a generic developer, which will be used by WSO2 API Management . Take a note of the user name, we will need it when configuring WSO2. "userName": "wso2-apim".

curl --location --request POST 'http://{connector_host}:{connector_port}/v1/{org_name}/developers' \
--header 'Content-Type: application/json' \
--user {org_admin_name}:{org_admin_pwd}> \
--data-raw '{
    "email": "apim@wso2.org",
    "firstName": "User",
    "lastName": "APIM",
    "userName": "wso2-apim"
}'

Integrating the Connector into WSO2 API Management

Open the <API-M_HOME>/repository/conf/deployment.toml file and add the following according to your account details. Make sure to restart the server after adding the configurations.

    [[apim.gateway.environment]]
    name = <Name of the Solace Environment>
    display_name = <Display Name of the Solace Environment>
    type = <Type of the Environment>
    display_in_api_console = <Displays the environment under 'Try it' in the API Developer Portal, in the API console>
    description = <Description about Solace Environment>
    provider = <Vendor name of the environment. (Must be "solace")>
    service_url = <Base URL of the Solace API-Management Connector>
    username = <Username of the Solace API-Management Connector account>
    password = <Password of the Solace API-Management Connector account>
    ws_endpoint = <WS Endpoint of the Solace PubSub+ Service>
    wss_endpoint = <WSS Endpoint of the Solace PubSub+ Service>
    http_endpoint = <HTTP Endpoint of the Solace PubSub+ Service>
    https_endpoint = <HTTPS Endpoint of the Solace PubSub+ Service>
    show_as_token_endpoint_url = false

    [apim.gateway.environment.properties]
    Organization = <Password of the Solace broker account>
    DevAccountName = <Password of the Solace broker account>

Note that only all these properties are mandatory, except show_as_token_endpoint_url.

Use the following values for the properties:

name: the environment name must match the name of the environment that was configured in the Connector (previous step)
display_name: the friendly name of the environment that is displayed in API Management.
type: you can use hybrid
display_in_api_console: true or false
description: description as displayed in API Management
provider: must be solace
service_url: the base URL of the Connector - http://{connector_host}:{connector_port}/v1
username: the username of an organisation level administrator (org-admin) that is configured in the Connector - {org_admin_name} in cURL examples above
password: the password of the organisation level administrator (org-admin) that is configured in the Connector - {org_admin_pwd} in cURL examples above
ws_endpoint: use the endpoint URI for the ws-mqtt protocol as returned by the services REST API call in the section above
wss_endpoint: use the endpoint URI for the wss-mqtt protocol as returned by the services REST API call in the section above
http_endpoint: use the endpoint URI for the http protocol as returned by the services REST API call in the section above
https_endpoint: use the endpoint URI for the https protocol as returned by the services REST API call in the section above
Organization: the organization name as configured in the Connector - {org_name}
DevAccountName: the name of the developer account - wso2-apim in the example configuration in the section above.

The Solace broker gateway is now available in the API Publisher.

Creating and deploying an API

You can use the Async API specification generated from the Solace PubSub+ Event Portal or any other source to create APIs in WSO2 API Manager.

Importing an Async API

Before you begin: Make sure that you have integrated the Solace event broker with WSO2 API Manager as shown in the above section.

Login to the API Publisher via https://<hostname>:9443/publisher
Click CREATE API and then click Import AsyncAPI Definition
The following two options to import the AsynAPI definition appear.

a. AsyncAPI URL - If you select this option, you need to provide a URL of a Solace API Specification. b. AsyncAPI File - If you select this option, click Browse File to Upload and upload a file, which contains a Solace AsyncAPI definition. Select your preferred method and click NEXT.

Info

If the Async API specification is a valid Solace Async API specification, the portal will display the Identified as Solace Event Portal API tag.

A valid Solace Async API specification must contain x-origin: vendor: solace extension like in this example

asyncapi: 2.2.0
info:
  title: WSO2 Sample
  version: 1.0.0
  description: Some description
  x-origin:
    vendor: solace

Edit the Solace Async API information and click Create.

Note

The Async API definition of the Solace API will contain the specific API definition, with the supported protocols, such as HTTP, MQTT, AMQP, that the API topics have to use. You do not need to provide the protocol information separately

Configuring Topics

Click Topics to navigate to the topics page.

The topics will be created automatically from the Solace AsyncAPI definition provided in the previous step.

Viewing the Async API definition

Go to API Configurations and click AsyncAPI Definition to see the definition of the API you created in the previous step.

Note

You can edit the AsyncAPI specification in API Manager Publisher Portal directly in AsyncAPI Definition viewer by clicking on Edit.

Warn

The current version of WSO2 API Manager only supports AsyncUnlimited Protocol as the API level subscription policy for Solace APIs. Once a subscription is made, that policy will be added automatically.

Deploying the API to the Solace PubSub+ environment

Navigate to the Deploy section and go to Deployments.
Select the Deployment environment and click Deploy.
The API revision will be created. Select the API revision and click Deploy.
The Solace API will be deployed to the Solace Broker environment that is user-provided.

Publishing the API

See Publish an API for instructions on publishing the API created in the previous steps.

Subscribing to an API

You have to subscribe to a published Solace API before consuming them. The subscription process fulfills the authentication process and provides you with access tokens that you can use to invoke an API. The subscription flow will be controlled by the WSO2 API Manager.

When the Application is attached with a Solace API Subscription, the solace broker will keep a copy of that Application for the authentication and validation process of the tokens generated by the WSO2 API Manager.

The following are the two methods available in the Developer Portal to subscribe an API to an application.

Subscribe to an existing application - You can subscribe to a current API by selecting an existing application.
Subscribe to an API using Key Generation Wizard - You can use the SUBSCRIPTION & KEY GENERATION WIZARD option to start the subscription process from scratch.

Note that the artifacts are deployed in the Solace broker, therefore API level and application-level throttling will not be supported for the Solace API subscriptions.

Invoking an API

In this section, you will subscribe to the AsyncAPI through the Developer Portal

Subscribing to the Solace API

Log in to the Developer Portal via https://:9443/devportal
Select your Solace API and navigate to the Overview.
Subscribe to your API using the sample application. You can also create a new application for this purpose.

Generating keys

In the sample application, click Production Keys and navigate to OAuth2 Tokens.
Locate the consumer key and consumer secret, these will be used as credentials to connect to the Solace PubSub+ service. For instructions on generating keys see, Application Keys.

Selecting the Async Protocol and Topic

Select the Solace API and click on the Solace Info section in the left menu. This will render an information page like the following.
Select the Application, Environment, and Protocol from the dropdowns of the info page. a. Application - Select the required application of the subscribed Application of the Solace API. b. Environment - Select the deployed Solace broker environment that needs to be used. c. Protocol - Type of the transport protocol to invoke the Async topics with. The topics supported for the selected Application, Environment and Protocol will be rendered.
Copy the endpoint URL of the protocol of the selected environment.
Copy the topic that needs to be consumed. Click on the Copy icon in front of the topic.
Then use this information to create a request on the desired protocol to invoke the topic and consume the topic.

Publishing messages using HTTP

If your Async API is available via HTTP you can use the information gathered above to publish an event using a simple HTTP POST.

You need the following information:

{endpoint_url}: the endpoint URL (http or https)
{topic}: a topic you wish to publish to
{consumer_key}: your consumer key for the appropriate environment
{consumer_secret}: your consumer secret for the appropriate environment

curl --location --request POST '{endpoint_url}/{topic}' \
--header 'Content-Type: application/json' \
--user {consumer_key}:{consumer_secret}> \
--data-raw '{
    "value": "1"
}'

Subscribing to messages using MQTT

If your Async API is available via MQTT you can use the information gathered above to subscribe to topics using an MQTT client.