community
cancel
Showing results for 
Search instead for 
Did you mean: 

Alteryx Promote Knowledge Base

Definitive answers from Promote experts.

Promote Rest API Call

Alteryx
Alteryx
Created on

Models deployed to Promote can be queried through a couple of different ways, one of them being a standard REST API post request. Querying a model consists of sending in the predictor variables to the model, allowing the model to process the data and make predictions. After the prediction is made from the model, the return is the score based on the predictor variables entered.

 

An example of a cURL call in promote:

promoteeee.png

 

 

 

 

 

 

 

 

 

 

 

 

  

 

 

I am going to walk you through on how to make this call in Designer. This API request can be replicated in any other application as well. Promote calls are broken down into 3 parts:

  1. Endpoint
  2. Authentication
  3. Data

 

Lets start with Endpoint:

Each deployment of a new model receives its own endpoint. This endpoint can be queries via an HTTP request. A POST method request must be made to call a model. Endpoints follow the pattern:

 

https://promote.yourcompany.com/<user_name>/models/<model_name>/predict

where:

<user name> : logged in user

<model_name>: model name when deployed to promote

 

When a new version of a model is deployed, the new model is read into memory. Once it's online and ready to take requests for predictions, it will be "hot-swapped" into the endpoint. This means there is zero downtime between deployments.

 

Authentication

Promote uses Baisc Auth for authentication predictions or API requests. In the HTTP header, provide the following:

Name: “Authorization”

Value: “Basic”

API_KEY: Your base64 encoded api key with the username

Content-Type: application/json

 

For example, if my credentials are the following:

Username: bob

API_KEY: 5a1d774c-1360-4tca-9c70-87f36916db0w

 

Translates to:

bob:5a1d774c-1360-4tca-9c70-87f36916db0w

 

Converting translation to base64:

m9iOjVhMWQ3NzRjLTEzNjAtNHRjYS05YzcwLTg3ZjM2OTE2ZGIwdw==

 

Putting it together:

Authorization: Basic m9iOjVhMWQ3NzRjLTEzNjAtNHRjYS05YzcwLTg3ZjM2OTE2ZGIwdw==

 

Most HTTP libraries should have a standard way of making a Basic request. For example, in Ruby it would look like:

require 'net/http'
require 'uri'
require 'json'
url = URI('https://promotesandbox.alteryx.com/bob/models/example1/')
# Create new request
req = Net::HTTP::Post.new(url.path)
# Encode basic auth
req.basic_auth "bob", "5a1d774c-1360-4tca-9c70-87f36916db0w "

 

Data

This is where you enter in the data required to make the prediction. This is sent in the request body as JSON (ex: {“name”: “bob”}).

 

All models use predictor variables to create a model. The number of predictor variables change from model to model but the basis is the same. If I wanted to create a model that predicts if a patient is likely to have a heart disease or not, some of the variables that I might want to account for would be:

  • chestpain, age, gender, cholesterol, smoker and exercise level

Converting the above variables to a JSON format:

 

{ 
"chestpain": 1,
"age": 50,
"gender": "M",
"cholesterol": 1,
"smoker": 0,
"exercise level": "daily"
}

 

The output from Promote would be:

 

{
  "status": "OK",
  "timestamp": "2018-12-17T21:51:00.703Z",
  "result": [
      {
"prediction.Score_0": 0.40457933469541,
"prediction.Score_1": 0.59542066530459
} ], "promote_id": "3ce8285f-dbee-4220-9e13-147757f8ed57", "model_name": "PredictingHeartDiseaseRisk", "model_version": "1" }

 

Putting it all together in the Download Tool:

 

 2018-12-17_17-49-52.png

 

In an input tool with 3 columns - endpoint (url), authentication, and data I want to send over.

 

 2018-12-17_17-40-12.png

 

For the URL, select the endpoint.

 

2018-12-17_17-41-15.png

 

For the Header tab, type in Content-Type as application/json and select the base64 encoded authorization. 

 

2018-12-17_17-43-07.png

 

For Payload, select the method to be POST and Take Query String/Body from Field as your Data. 

 

 2018-12-18_2-15-46.png

 

The output should be something like this with a 200 OK Response. It will also have the prediction score depending on the data payload.

 

 

{"result":[{"prediction.Score_0":0.40457933469541,"prediction.Score_1":0.59542066530459}],"promote_id":"05ecdf93-e40a-4093-96b4-27bd2g0f3481","status":"OK","timestamp":"2018-12-18T07:14:05.913Z","model_name":"PredictingHeartDiseaseRisk","model_version":"1"}
  

Extras:

Promote also contains several other endpoints for getting the status and general information about the deployed models.

 

Description

Method

Route

Predict

POST

http://promote_url/<username>/models/<model>/predict

List all models

GET

http://promote_URL/api/models

Model versions

GET

http://promote_url/api/models/<user>/<model>/versions

Model info

GET

http://promote_URL/<username>/models/<modelname>/info

System info

GET

http://promote_URL/api/metrics

 

Currently the following languages are supported for application integration:

Select the appropriate code in the Sample tab in the Promote UI and paste the code snippet into the production or development environment.

 

More information for Model Management and endpoints can be found here.