Create web API with CLI

Introduction

In this page, we explain the flow of creating a web API for a simple model using CLI of ABEJA platform.

Configure ABEJA Platform CLI

It is possible to create, update and delete a model using ABEJA Platform CLI.

Installation

Before install ABEJA Platform CLI, check the operational environment from here.

$ curl -s https://packagecloud.io/install/repositories/abeja/platform-public/script.python.sh | bash
$ pip install abejacli

Reference: ABEJA Platform CLI

Configuration

Please set the authentication information of ABEJA Platform.

$ abeja config init
User ID              : {USER_ID}
Personal Access Token: {PERSONAL_ACCESS_TOKEN}
Organization ID      : {ORGANIZATION_ID}
[INFO]: ABEJA credentials setup completed!

Reference: ABEJA Platform CLI

Create sample model

Download sample model

Download the source code of the sample model from here. This source code is an implementation of a simple calculation function.

Copy the source code to a python file main.py and placed this file in an empty directory and execute the command from that directory location.

$ ls
main.py
$ cat main.py
def handler(iter, context):
   for line in iter:
       if 'total_without_tax' not in line:
           raise context.exceptions.InvalidInput('total_without_tax not in the request')
       total_without_tax = line['total_without_tax']
       total_without_tax = int(total_without_tax)
       total = total_without_tax * 1.08
       yield {'total': total}

Execute handler function locally

Before start to create the Web API on the cloud, make sure that the sample model works on locally.

Prepare the following JSON file as test input of model handler function.

$ cat request.json
{
  "total_without_tax": 100
}

You can run the handler function of the sample model by run-local command.

Since the function name in main.py is handler, pass main:handler as the value of --handler option.

The final output of handler function will show for the input request.json.

$ abeja model run-local --image abeja/all-cpu:18.10 --handler main:handler --input request.json
[info] preparing image : abeja/all-cpu:18.10
...
[info] building image
...
[info] setting up local server
...
[info] waiting server running
...
[info] sending request to model
...
[info] finish requesting to model
{'total': 108.0}

Reference: ABEJA PlatformCLI: run-local

Create Model

Create the model with create-model command.

--name and--description are any identifiable strings.

$ abeja model create-model --name getting-started --description "this is a getting-started example model"
{
    "created_at": "2018-05-01T02:07:16.459526Z",
    "description": "this is a getting-started example model",
    "model_id": "1111111111111",
    "modified_at": "2018-05-01T02:07:16.459641Z",
    "name": "getting-started",
    "versions": []
}

Reference: ABEJA PlatformCLI: create-model

Create Model Version

Create model version by using create-version command.

--model_id is a model identifier, created by create-model command.

$ abeja model create-version --model_id {MODEL_ID} --version 0.0.1 \
                             --image abeja-inc/all-cpu:18.10 --handler main:handler
{
    "version": "0.0.1",
    "version_id": "ver-1111111111111111"
}

Reference: ABEJA PlatformCLI: create-version

Create Deployment

Create deployment using create-deployment command.

--model_id is a model identifier, created by create-model command.

$ abeja model create-deployment --name getting-started --model_id {MODEL_ID}
{
    "created_at": "2018-05-02T04:46:04.469269Z",
    "daemons": [],
    "default_environment": {},
    "deployment_id": "2222222222222",
    "model_id": "1111111111111",
    "modified_at": "2018-05-02T04:46:04.469381Z",
    "name": "getting-started",
    "runs": [],
    "services": [],
    "triggers": []
}

Reference: ABEJA PlatformCLI: create-deployment

Create Service

Create service with create-service command for a model version as a web API.

For --deployment , specify the deployment identifier created with the create-deployment command and --version_id , specify the version identifier created with thecreate-version command.

$ abeja model create-service --deployment_id {DEPLOYMENT_ID} --version_id {VERSION_ID}
{
    "created_at": "2018-05-02T05:38:19.312332Z",
    "deployment_id": "2222222222222",
    "instance_number": 1,
    "instance_type": "cpu-0.25",
    "metrics_url": "https://p.datadoghq.com/sb/aaaaaaaaa-6951475d7c4b91c840dbe30a07652620",
    "model_version": "0.0.1",
    "model_version_id": "ver-1111111111111111",
    "modified_at": "2018-05-02T05:38:21.301214Z",
    "service_id": "ser-1111111111111111",
    "status": "IN_PROGRESS",
    "user_env_vars": {}
}

Reference: ABEJA PlatformCLI: create-service

Confirm activation status of created service

Make sure that the service is available.

Use describe-services command to check the status of the service. Confirm the status is READY.

$ abeja model describe-services --deployment_id {DEPLOYMENT_ID}
{
    "entries": [
        {
            "created_at": "2018-05-02T05:38:19.312332Z",
            "deployment_id": "2222222222222",
            "instance_number": 1,
            "instance_type": "cpu-0.25",
            "metrics_url": "https://p.datadoghq.com/sb/c61020b12-6951475d7c4b91c840dbe30a07652620",
            "model_version": "0.0.1",
            "model_version_id": "ver-1111111111111111",
            "modified_at": "2018-05-02T05:38:21.301214Z",
            "service_id": "ser-1111111111111111",
            "status": "READY",
            "user_env_vars": {}
        }
    ]
}

Reference: ABEJA PlatformCLI: describe-services

Confirm the operation of created service

Call the web API service created by create-service command and check the response.

Using simple checking tool

Use check-endpoint-json command to check the web API for JSON inputs.

$ abeja model check-endpoint-json --deployment_id {DEPLOYMENT_ID} --service_id {SERVICE_ID} \
                                  --key total_without_tax --value 100
{
    "total": 108.0
}

Using curl

By using curl, you can send a request and check the default endpoint with the following command.

$ curl  --user user-{ABEJA-PLATFORM-USER}:{PERSONAL-ACCESS-TOKEN} \
        -H 'Content-Type:application/json' \
        -XPOST -d '{"total_without_tax": 100}' \
        https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/services/{SERVICE_ID}

Specify alias name of service (create endpoint)

It is possible to create an alias (end point) using create-endpoint command for a specific service. You can check the created endpoint by describe-endpoints command.

To use this activated service need to request to https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/services/{SERVICE_ID}. By giving an alias you can access it as https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/{alias}

Reference: ABEJA PlatformCLI: create-endpoint

Reference: ABEJA PlatformCLI: describe-endpoints

$ abeja model create-endpoint --deployment_id {DEPLOYMENT_ID} --service_id {SERVICE_ID} \
                              --custom_alias default
{
    "custom_alias": "default",
    "endpoint_id": "pnt-1111111111111111",
    "service_id": "ser-1111111111111111"
}

Confirm the operation of created endpoint

Call the endpoint created by create-endpoint command and check the response.

Using simple check tool

Use check-endpoint-json command to check the web API for JSON inputs.

$ abeja model check-endpoint-json --deployment_id {DEPLOYMENT_ID} \
                                  --key total_without_tax --value 100
{
    "total": 108.0
}

Using curl

To check the service using curl need to make the following request.

$ curl  --user user-{ABEJA-PLATFORM-USER}:{PERSONAL-ACCESS-TOKEN} \
        -H 'Content-Type:application/json' \
        -XPOST -d '{"total_without_tax": 100}' \
        https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}