How to Expose an Integration Service as a Managed API¶

What you'll build¶

In this tutorial, you'll define an integration service using Micro Integrator Extension for Visual Studio Code (MI for VS Code) and expose it as a managed API to the API marketplace. API consumers then discover the API from the marketplace, subscribe to it, and use it for application development.

This demonstrates how the integration components and API management components of WSO2 API Manager work together to enable API-led integration. The following diagram illustrates the various API Manager components and the different user roles that are involved in implementing this process:

An Integration Developer creates the service using Micro Integrator Extension for Visual Studio Code (MI for VS Code) and deploys it in the Micro Integrator runtime.

Note

The integration service is designed to communicate with a back-end service (representing a Hospital) and get details of available doctors for various specializations.
An API Creator converts the integration service to a managed API (apply security, rate limiting, etc.).
An API Publisher publishes the API to the API marketplace (Developer Portal).
An API Consumer (application developer) discovers and uses this API from the Developer Portal.

Concepts and artifacts used¶

The following concepts and artifacts are used in this tutorial:

REST API / Integration Service
Endpoints
Mediators
Service Catalog
API Publisher
API Developer Portal

Let's get started!¶

Follow the steps given below to build this use case and try it out.

Step 1: Set up the workspace¶

The following software and configurations are required to proceed with this tutorial:

Visual Studio Code (VS Code): with the Micro Integrator extension installed.
Java Development Kit (JDK): Ensure the JDK is properly configured in your system's PATH environment variable.
Apache Maven: Ensure Apache Maven is installed and its path is correctly set within the system's PATH environment variable.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.

Step 2: Develop the integration artifacts¶

Follow the instructions given in this section to create and configure the required artifacts.

Create an Integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter ServiceCatalogSample as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create HTTP Connection¶

Navigate to Micro Integrator Project Explorer.
Click on the + symbol to open the Add Artifact pane.
Click + View More under Create an Integration.
Select Connections under Other Artifacts to open the Connector Store Form.
Select Http.

In the Add New Connection form, specify the following values to create the new HTTP connection.

Property	Value	Description
Connection Name	`QueryDoctorConn`	The name of the connection.
Base URL	`http://localhost:9090/healthcare`	The base of the request URL for the back-end service.

Click Add.

Create a REST API¶

A REST API is required for receiving the client requests and the REST resource within the API will define the mediation logic that will send requests to the Healthcare back-end service and retrieve the available doctor information.

Go to MI Project Explorer > + Add Artifact > API.

Specify values for the required REST API properties:

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare`.

Click Create. This opens the Service Designer interface.

You can now start configuring the API resource.
Click on the GET API resource under Available resources on the Service Designer.

You will now see the graphical view of the HealthcareAPI with its default API Resource.
Click the Edit icon to edit the API resource.

Specify values for the required resource properties:

Property	Description
Resource Path	`/querydoctor/{category}` This defines the request URL format. In this case, the full request URL format is `http://host:port/querydoctor/{category}` where `{category}` is a variable.
Methods	`GET` This defines that the API resource only handles requests where the HTTP method is GET.

Click Update.

Create the mediation logic¶

You can now configure the mediation logic to handle requests.

To get started, click on the + icon to add the first mediator to the sequence.
Select Log mediator in the Mediators section. The Log mediator logs messages when the request is received by the API resource. In this scenario, let's configure the Log mediator to display the following message: “Welcome to the HealthcareService”.

Once you select the Log mediator, the Log pane will be opened. Fill in the information in the table below:

Field	Value	Description
Log Category	`INFO`	Indicates that the log contains an informational message.
Message	`Welcome to HealthcareService`	Indicates the message.
Description	`Request Log`	The Description field provides the name that appears for the Log mediator icon in the design view.

Click Submit to save the Log mediator configuration.

Let's configure a GET operation to send the request message to the HealthcareService endpoint and receive the response message.
Click on the + icon in the sequence to add a GET operation for QueryDoctorConn after the Log mediator. From the palette, select Mediators > HTTP > GET operation.

Once the GET operation form is opened, fill in the information in the table below:

Field	Value	Description
Connection	`QueryDoctorConn`	The connection to be used to execute the operation.
Relative Path	`/${params.pathParams.category}`	Indicates the relative path added to the base URL of the connection. In this case, the variable 'category' that needs to be included in the request for querying doctors is represented as `{params.pathParams.category}` in the relative path.

Click Submit.

Now let's add a Respond mediator at the end of the sequence to send the response message from the healthcare service back to the client.
Click on the + icon below the GET operation in the sequence to add a Respond mediator.
From the Palette, select Respond mediator under the Mediators section.
Click Submit.

You have successfully created all the artifacts that are required for sending a request through the Micro Integrator to the back-end service.

Step 3: Configure the Micro Integrator¶

Prerequisites

Before you begin, install Micro Integrator on your machine:

Go to the WSO2 Micro Integrator web page, click Download, provide the necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.
Extract the ZIP file. The extracted folder will be referred to as the <MI_HOME> folder.

The Micro Integrator can automatically publish artifacts to the Service Catalog in the API Publisher portal.

Let's enable this feature in the Micro Integrator.

Uncomment the [[service_catalog]] section as shown below and change the APIM server configurations accordingly in the <MI_HOME>/conf/deployment.toml file.

Tip

The default username and password for connecting to the API gateway is admin.
```
[[service_catalog]]
apim_host = "https://localhost:9443"
enable = true
username = "admin"
password = "admin"
```

Note

Since the integration developer may not know the API URL when it gets deployed in the Micro Integrator, the URL of the API will be parameterized as https://{MI_HOST}:{MI_PORT}/healthcare which will be resolved later using environment variables MI_HOST and MI_PORT respectively. By default, localhost will be used as the MI_HOST and 8253 as the MI_PORT. Depending on your deployment, you may need to update these environment variables.

Step 4: Start the API Manager runtime¶

Let's start the API Manager runtime before starting the Micro Integrator.

Download and set up WSO2 API Manager.
Start the API-M server.

Step 5: Build and run the artifacts¶

Click on the Command Palette at the top of the VS Code.
Type > to show the available commands.
Select MI: Add MI server.
Select Add MI server.
Select the folder where <MI_HOME> is located. This will be set as the current server path.
Run the project.

Click the Build and Run icon located in the top right corner of the VS Code.

When the Micro Integrator starts, the integration service will be deployed to the Service Catalog during server startup. You will see the following in the server start-up log.

Successfully updated the service catalog

Step 6: Create and Deploy the API¶

Create the API

Let's expose the integration service as a managed API.

Sign in to the API Publisher portal: https://localhost:9443/publisher.

Tip

Use admin as the username and password.
You can also click the hamburger icon on the upper-left and click Services to see the available services.
Open HealthcareAPI from the above list.
Click Create API in the above screen to open the Create API dialog box.
Specify an API name, context, and version, and then click Create API.

Tip

You will find these values already populated based on the information in the integration service.

You can now see the new API's overview page.

Note

You can use the left-hand navigation to explore the new API.
Click Endpoints in the left-hand navigator. You will see that the new API uses the integration service deployed in the Micro Integrator as the endpoint (backend).

Select business plans

Let's allocate some business plans for the API.

Go to the API overview and click Business Plan.
Select at least one business plan for the API and save.

Deploy API in the Gateway

Let's deploy the API in a gateway environment.

Go to the API overview and click Deploy.

Tip

This opens the Deployment tab in the left-hand navigator.
Click Default to specify the gateway environment and host.

Tip

This setting deploys the API in Production as well as Sandbox gateways. Find out more about gateway environments.
Optionally, you can add a description.
Click Deploy.

You will now see the deployment as the first revision of the API:

Step 7: Publish the API¶

Go to the API overview in the Publisher portal and click Publish for the HealthcareAPI as shown below.

The API is now available in the Developer portal for consumers to access.

Step 8: Use the API¶

Before you begin

Let's start the back-end hospital service.

Download the JAR file of the back-end service from here.
Open a terminal and navigate to the location of the back-end service
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Sign in to the Developer portal: https://localhost:9443/devportal/apis.

Tip

Use admin as the username and password.
Go to the API tab. The HealthcareAPI is listed as shown below.
Select the HealthcareAPI to open the API overview.
Click API Console under Try Out for the HealthcareAPI in the Developer portal as shown below.
Enter the username and password for Basic Authentication.

Tip

Use admin as the username and password.
Expand the /querydoctor/{category} resource and click Try it out.
Specify surgery as the doctor category.
Click Execute.

You will get the response message from the Healthcare service, if you send the category as surgery:

[
    {
        "name":"thomas collins",
        "hospital":"grand oak community hospital",
        "category":"surgery",
        "availability":"9.00 a.m - 11.00 a.m",
        "fee":7000.0
    },
    {
        "name":"anne clement",
        "hospital":"clemency medical center",
        "category":"surgery",
        "availability":"8.00 a.m - 10.00 a.m",
        "fee":12000.0
    },
    {
        "name":"seth mears",
        "hospital":"pine valley community hospital",
        "category":"surgery",
        "availability":"3.00 p.m - 5.00 p.m",
        "fee":8000.0
    }
]

Now, check the OUTPUT tab of VSCode and you will see the following message:

INFO {LogMediator} - {api:HealthcareAPI} Log Property message = "Welcome to HealthcareService"

Tip

For detailed instructions see Invoke an API using the Integrated API Console.