[Tutorial] How To Build Predictive APIs with WSO2 API Manager and WSO2 Machine Learner

Table of contents

• Applies to
• Introduction
• What is a predictive API?
• Training a predictive model in WSO2 Machine Learner
• Creating the predictive API in WSO2 API Manager
• Usage of the predictive API
• Conclusion
• References

Applies to

Introduction

Creating applications with the ability to learn from available data and making decisions based on the prediction results obtained from the learned models has become a trend-setting aspect in the software industry. For this task, implementation of machine learning algorithms from scratch is not a recommended way because of

1. Complexity of machine learning algorithms
2. Additional resources required
3. Additional maintenance costs
4. Already available high-performance, easy-to-use machine learning engines

Therefore, almost all applications that do predictive modeling uses one or more of these already available machine learning engines. With the ability to directly interact with these engines with simple API calls, intricacy of integration has alleviated rapidly. One of the common practices is training models with machine learning engines and building predictive APIs on top of them to retrieve prediction results for a new event.

This article discusses how to train a machine learning model with WSO2 Machine Learner and create a predictive API with WSO2 API Manager with the trained model.

What is a predictive API?

A predictive API is an API that you can invoke and get predictions for a new event/data item from a pre-trained machine learning model as the response. Figure 1 depicts the interactions between WSO API Manager and WSO2 Machine Learner and the external application that invokes the predictive API.

Figure 1: External application invoking a predictive API

1. Creating and preprocessing the dataset with WSO2 Machine Learner
2. Training the model from the dataset and storing the model
3. Invoking the predictive API in WSO2 API Manager
4. WOS2 API Manager calls the REST endpoint of WSO2 Machine Learner with a new data item
5. WSO2 Machine Learner retrieves the prediction with feature values from the stored model
6. WSO2 Machine Learner sends the response with the prediction to WSO2 API Manager
7. WSO2 API Manager sends the prediction result to the output

In order to to create the predictive API from WSO2 API Manager, a pre-trained model is required.

Training a predictive model in WSO2 Machine Learner

The first step of building a predictive API is training the model. Figure 2 depicts the main stages of creating a predictive model in WSO2 Machine Learner.

Figure 2: Predictive modeling flow with WSO2 Machine Learner

Steps in predictive modeling with WSO2 Machine Learner are as follows:

1. Creating a dataset
2. Creating a project
3. Creating an analysis
4. Train a model
5. Predict with the model

To demonstrate this procedure, we will use breast cancer details in Wisconsin dataset that is located in the <ML_HOME>/samples/tuned/logistic-regression-lgbfs/breastCancerWisconsin.csv file.

In a real-world scenario, you may use historical data collected from sensors, log files, databases, etc. for this purpose.

The following steps explain the process of training a model in WSO2 Machine Learner with the Wisconsin breast cancer dataset.

1. Login to WSO2 Machine Learner with your user credentials and click Add Dataset in the homepage. In create dataset page, provide the dataset name and dataset version then browse the data source and select the breastCancerWisconsin.csv file. Click create dataset after you have filled the required fields.
   
   

   Figure 3

2. After you create the dataset, you will be redirected to the datasets page. From there, click Create Project located on the dataset you have created. At the project creation page, give a name for your project and and click Create Project.
   
   

   Figure 4

3. Once you create the project, you need to create an analysis. Fill the analysis name field and click Create Analysis. You will be directed to data preprocessing page. Select the feature you want to keep in the analysis. Note that feature Class is the response variable (what we need to predict) of this dataset; therefore, the selected feature set should include Class. Click Next until you get to algorithm selection page. The Class feature has two unique values: “2” to indicate the benign state and “4” to indicate the malignant state of the breast cancer. From there, select RANDOM FOREST CLASSIFICATION as the algorithm and Class as the response variable. We choose classification because what we have to predict is one of two values [1].
   
   

   Figure 5

4. Click Next to go to the parameter tuning page. You may change the hyper parameters of random forest regression algorithm as you prefer. Click Next to go to the dataset version selection page. Select the available dataset version you have created and click Run to train the model.
   
   

   Figure 6

5. After the model has been trained successfully, you will be able to update the Status of the model as Complete as illustrated in Figure 6. You can see the model evaluation results by clicking View located on the model.

Once the model training has been successfully completed, in the command prompt, you will be able to see the model ID of the trained model as indicated in Figure 7. Here it is 6.

Figure 7

You will need this model ID, when you create the predictive API from this model.

Alternatively, you can use the following command to retrieve the model ID of the given model name from the machine learner.

curl -H "Content-Type: application/json" -H "Authorization: Basic YWRtaW46YWRtaW4=" -v https://{ML_HOST}:{ML_PORT}/api/models/breast_cancer_analysis.Model.2016-05-04_20-51-11 -k

In the authorization header, you need to add the base64 encoded {user_name}:{password}. Value in the above command is for admin:admin. The response for this command will provide you the information of the model with the name: breast_cancer_analysis.Model.2016-05-04_20-51-11 (the models will be saved in the {ML_HOME}/models folder, so you can view the model name from that folder as well). Note down the “id” from the response.

Creating the predictive API in WSO2 API Manager

WSO2 API Manager invokes the REST API of WSO2 Machine Learner to get predictions from a set of feature values. For this, WSO2 Machine Learner’s prediction API needs to be set as an endpoint in WSO2 API Manager. The following steps demonstrate how to add the prediction API as an API in WSO2 API Manager.

1. The REST API of WSO2 Machine Learner is secured with basic authentication. These secured endpoints are HTTPS endpoints. In order to enable HTTPS endpoints in API Manager, set the <parameter name="HostnameVerifier"> element to AllowAll in the <APIM_HOME>/repository/conf/axis2/axis2.xml file's HTTPS transport sender configuration [2].

   <parameter name="HostnameVerifier">AllowAll</parameter>
   

2. Start WSO2 API Manager and log in to the API publisher. Go to Add in the right panel and select Design new API, then click Start creating.
3. You will be redirected to to the API creation page. In that page, set the following fields:
   • Name: BreastCancerPredictionAPI
   • Context: api
   • Version: v11

   Then add an API with the URL pattern/predict with POST method. In configurations, set the Parameter type as “body” and Required as “True” as indicated in figure 8. Then click Next: Implementation >

   

   Figure 8

4. Select “Managed API” from the implementation page. Set the following configurations for the managed API
   • Endpoint type: HTTP
   • Production Endpoint: https://{ML_HOST}:{ML_PORT}/api/models/{model_ID} (put the model ID of the trained model you have noted down earlier)
   • Endpoint security scheme: Secured
   • Endpoint Auth type: Basic
   • Credentials: ML username, ML password
   

   Figure 9

   Then click Next: Manage >

5. In the Manage page select your preferred tier availability then click Save & Publish.
   
   

   Figure 10

Now you have successfully created and published a predictive API for breast cancer prediction.

Usage of the predictive API

We will use the the API console in the API Store of WSO2 API Manager to demonstrate how to test/use predictive API we have created. The following steps discuss how to test the API:

1. Log in to the API Store of WSO2 API Manager. In the APIs section, you will be able to see the newly published API BreastCancerPredictionAPI - v11.
2. Select the BreastCancerPredictionAPI and subscribe to that with an application.
3. Go to My Subscriptions section and generate an access token for the production environment.
4. Again go the BreastCancerPredictionAPI and go to the API Console.
5. Choose Post/predict method and in the payload and enter the following feature vector:
   

   [
   [1000025,5,1,1,1,2,1,3,1,1]
   ]
   

   

   Figure 11

   This is the data item that we want to make predictions with, i.e. we want to know whether it is benign or malignant for a patient with these characteristics.

6. Click Try it out. You will be able to see the prediction result as “2” which indicates benign state.
   
   

   Figure 12

Conclusion

WSO2 Machine Learner offers you the ability to build a predictive model with ease and you will be able to leverage its ability to scale in order to employ datasets of varying sizes and with multiple number of data sources. Exposing the predictive capabilities of WSO2 Machine Learner with well-designed APIs effectively add one of the most imperative requirements of today’s software applications. With the help of WSO2 API Manager, you can design a predictive API that includes many API management features with minimum effort.

References

• [1] https://docs.wso2.com/display/ML110/Machine+Learner+Algorithms
• [2] https://docs.wso2.com/display/AM1100/Working+with+Endpoints