Table of Contents

Machine Learning APIs

Hardik Chheda Updated by Hardik Chheda

This is the documentation for the flow to be followed by external client to consume Tellius External APIs.

Connection management

Create Client

For more information about creating a client, see OAuth Access.

APIs

Get Access token

URL

/oauth/client_credentials_token

Method

POST

URL Parameters

None

Content type

application/x-www-form-urlencoded

Data parameters

Parameter name

Description

Mandatory

client_id

Client ID - Unique identifier for the client created in Tellius application

Yes

client_secret

Secret Key - Secret Key for the Client specified in above parameter

Yes

grant_type

Type of the grant. Valid grant types supported are

●     client_credentials

Yes

Example request:
curl -X POST http://uat1.app.tellius.com/oauth/client_credentials_token \

-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id=simple-client-id-for-documentation&client_secret=testSecretKeyStoreSafe&grant_type=client_credentials'
Example response:
{
    "access_token": "uniqueOAUTH2TokenForAccess",
    "refresh_token": "uniqueOAUTH2TokenForRefresh",
    "token_type": "bearer"
}
Response parameters : NN

Parameter name

Description

access_token

OAUTH2 token used to access the API endpoints

refresh_token

OAUTH2 token used to refresh the access_token, when expired

token_type

Type of the token

Once we successfully get the access_token and refresh_token from the API, we would be using the access_token in the below APIs

Refresh Access token

URL

/oauth/refresh_token

Method

POST

URL Parameters

None

Content type

application/x-www-form-urlencoded

Data parameters :

Parameter name

Description

Mandatory

refresh_token

Refresh_token received in /oauth/client_credentials_token API response

Yes

secret

Secret Key - Secret Key for the Client specified in above parameter

Yes

grant_type

Type of the grant. Valid grant types supported are

●     refresh_token

Yes

 Example request:
curl -X POST http://uat1.app.tellius.com/oauth/refresh_token \

-H 'content-type: application/x-www-form-urlencoded' \
-d 'refresh_token=uniqueOAUTH2TokenForRefresh&secret=testSecretKeyStoreSafe&grant_type=refresh_token'
 Example response:
{
    "access_token": "refreshedUniqueOAUTH2TokenForAccess",
    "refresh_token": "refreshedUniqueOAUTH2TokenForRefresh",
    "token_type": "bearer"
}
Response parameters:

Parameter name

Description

access_token

OAUTH2 token used to access the API endpoints

refresh_token

OAUTH2 token used to refresh the access_token, when expired

token_type

Type of the token

Once we successfully get the access_token and refresh_token from the API, we would be using the access_token in the below APIs

ML Prediction

Predict API - Data in payload

URL

/proxy/ml/external/predict

Authorization Header

Bearer uniqueOAUTH2TokenForAccess

Method

POST

URL Parameters

None

Content type

application/json

Data parameters:

Parameter name

Description

Mandatory

modelId

Id of the model trained in Tellius application to be used for prediction

Yes

data

Array of data in JSON format

Yes

Example request:
curl -X POST \

http://uat1.app.tellius.com/proxy/ml/external/predict \
  -H 'Authorization: Bearer uniqueOAUTH2TokenForAccess' \
  -H 'content-type: application/json' \
  -d '{
      "modelId":"externalMLApiTestModelId",
      "data":[{
            "age":39,
            "workclass":"State-gov",
            "education_num":13,
            "sex":" Male",
            "capital_gain":2174,
            "capital_loss":0
      },

      {
            "age":42,
            "workclass":"Private",
            "education_num":13,
            "sex":"Male",
            "capital_gain":5178,
            "capital_loss":0
      }]
}'
Example response:
{"data": 
    [{
        "education_num": "13.0",
        "age": "39.0",
        "capital_loss": "0.0",
        "sex": " Male",
        "capital_gain": "2174.0",    
        "workclass": " State-gov",
        "salary_prediction": " >50K",
        "salary_probability": "0.5741941021630615"
        },
     {
        "education_num": "13.0",
        "age": "42.0",
        "capital_loss": "0.0",
        "sex": " Male",
        "capital_gain": "5178.0",
        "salary_prediction": " >50K",
        "workclass": " Private",
        "salary_probability": "0.8135191477287123"
      }
    ]
}
 Response parameters:

Parameter name

Description

data

Data with prediction and probability/residual columns.

●     Probability will be added for Classification algorithms

●     Residual will be added for Regression algorithms

 Predict API - Data through file upload

URL

/proxy/ml/external/predict/file

Authorization Header

Bearer uniqueOAUTH2TokenForAccess

Method

POST

URL Parameters

None

Content type

multipart/form-data; boundary=----WebKitFormBoundaryWdrkgnD

Form parameters:

Parameter name

Parameter type

Description

Mandatory

metadata

Text

Stringified JSON object specifying the format of the uploaded file and modelId to be used for prediction

Yes

content

File

File which contains data to be predicted

Yes

 Metadata parameter structure:

Parameter name

Description

Mandatory

sourceType

Type of file being uploaded. The supported file types are:

  • json
  • csv

Yes

modelId

Id of the model trained in Tellius application to be used for prediction

Yes

options

Source specific configurations

 

CSV:

  • Each row should contain valid comma separated fields
  • Supported configuration options are:
    • header - true, if the first line in the file is the header row. False, if not.
    • delimiter - delimiter for different fields per row. Default value is comma(,)

JSON:

Example request:
 curl -X POST \

http://uat1.app.tellius.com/proxy/ml/external/predict/file \

  -H 'Authorization: Bearer uniqueOAUTH2TokenForAccess' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundaryWdrkgnD' \
  -F 'metadata={
       "sourceType":"csv",
       "modelId":"externalMLApiTestModelId",
       "options": {
            "header":"true"
       }
   }' \
  -F content=@adult_salary_train.csv
Example response :
 {
    "predictedDataId": "externalPredict_9c09cc3c-f670-4839-9ec6-7b778a68" 
}
Response parameters:

Parameter name

Description

predictedDataId

Unique uuid which is an identifier for the predicted data.

 Note: The maximum file size can be 250 MB.

Predicted data Download

URL

/proxy/ml/external/predict/download

Authorization Header

Bearer uniqueOAUTH2TokenForAccess

Method

GET

Content type

None

Data parameters

None

URL Parameters:

Parameter name

Description

Mandatory

predictedDataId

Unique uuid which is an identifier for the predicted data received in the /predict/file API response

Yes

Example request:
curl -X GET \
'http://uat1.app.tellius.com/proxy/ml/external/predict/download?predictedDataId=predictedDataIdRecievedFromFileAPI' \

    -H 'Authorization: Bearer uniqueOAUTH2TokenForAccess'
Response headers:

Predicted data would be streamed in the response, will be of type text/csv with utf-8 encoding

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Disposition: attachment; filename=
Server: akka-http/2.3.11
Date: Thu, 22 Dec 2016 09:13:32 GMT
Content-Type: text/csv; charset=UTF-8
Content-Length: 4860

Predicted data view

URL

/proxy/ml/external/predict/view

Authorization Header

Bearer uniqueOAUTH2TokenForAccess

Method

GET

Content type

None

Data parameters

None

URL Parameters:

Parameter name

Description

Mandatory

Default value

predictedDataId

Unique uuid which is an identifier for the predicted data received in the /predict/file API response

Yes

-

nrows

Number of rows to be sent in the response

No

200

rowoffset

Offset index of the rows, can be used for viewing the full data in paginated manner

No

0

Example request:
curl -X GET \

'http://uat1.app.tellius.com/proxy/ml/external/predict/view?predictedDataId=predictedDataIdRecievedFromFileAPI&nrows=200&rowoffset=0' \

  -H 'Authorization: Bearer uniqueOAUTH2TokenForAccess'
Example response :
 {
    "data": 
        [{
            "education_num": "13.0",
            "age": "39.0",
            "capital_loss": "0.0",
            "sex": " Male",
            "capital_gain": "2174.0",
            "workclass": " State-gov",
            "salary_prediction": " >50K",
            "salary_probability": "0.5741941021630615"
          },
          {
            "education_num": "13.0",
            "age": "42.0",
            "capital_loss": "0.0",
            "sex": " Male",
            "capital_gain": "5178.0",
            "salary_prediction": " >50K",
            "workclass": " Private",
            "salary_probability": "0.8135191477287123"
           }  
         ]}
Response parameters:

Parameter name

Description

data

Data with prediction and probability/residual columns.

●     Probability will be added for Classification algorithms

●     Residual will be added for Regression algorithms

 Sample Loan Risk App

 

Did we help you?

Contact