Skip to content

Requests

Deployments and Pipelines in UbiOps receive data through their REST API endpoints.

Before making a request, a Deployment or Pipeline should already have been created in the platform.

There are 2 types of requests: direct and batch requests. A direct request takes a single data point and keeps a connection open, after which the result is returned immediately. A batch request can take up to 250 data points (deployments) or 100 data points (pipelines), for each of them a separate request_id is returned with which the results can be retrieved at a later time. Direct requests are synchronous whereas batch requests are asynchronous.

Deployment Requests using the WebApp

You can easily create deployment requests using the UbiOps WebApp. This comes in handy when testing if your deployment behaves as it should. The WebApp will create the API request for you.

You can test your deployment by creating a direct request for it.

  1. Click on Deployments in the sidebar on the left and then click on your deployment name.

  2. Now click CREATE REQUEST and insert or upload the data you want to include in the test request. Click Create direct request to create the request.

Default version

This will make a request to the default version of your deployment. If you want to create a request for a specific deployment version, first navigate to the specific deployment version by clicking on its name in the versions table. Then, you can find the same button CREATE REQUEST to make a request to that specific version.

  1. When the deployment has finished processing, you can see the results of your request.

You can also create batch requests in a similar fashion if you click Create batch requests in the request pop up.

Deployment Requests using the API

The following text describes how to send data to a Deployment or Pipeline using the UbiOps API and applies to both deployment and pipeline requests. For examples see Request examples

API Token

For sending data to a deployment through the UbiOps API you will need an API Token with the correct permissions.

To make a request you need to provide the project name, deployment name or pipeline name, and the request data. There are different API endpoints for direct and batch requests for dpeloyments an pipelines. In case of deployments/pipelines with structured input, you need to provide a JSON dictionary with the input fields of the deployment/pipeline as keys and the data as values. In case of batch request, you need to provide a list of dictionaries containing the input fields of the deployment/pipeline as keys and the data as values. In case of plain deployments, a single string or list of string input is required that will be sent as-is to the deployment. In case of batch request, a list of string input is required.

Below you can see an example of how to format the request data for a batch request. Making a batch request to a deployment in UbiOps

Deployment request endpoints:

Pipeline request endpoints:

The endpoints linked to above will make a request to the default version of you deployment or pipeline. If you want to make a request to a specific version that is not the default version, then you can use the deployment version request endpoint, or the the pipeline version request endpoint. For a full list of available API endpoints related to requests in UbiOps, please see Swagger.

Making blob requests

If your deployment takes in a blob as input, you have to provide the id of the blob in the input.

Retrieve the request results through the API

The result of a direct request is always immediate, meaning that the result is returned as soon as its computed. If your deployment was idle before the request, this can take a bit longer than when the deployment was still active.

When you make a batch request, the following response is returned per data point:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "pending",
    "time_created": "2020-07-24T09:51:15.360Z"
  }
]

The status of the request is always pending upon initialization and will later change into processing, failed or completed.

After making the request, you can collect the result of the request with the request id returned upon making the request. You can either collect the result of a single request or the results of multiple requests.

For the results of one batch request, you can use the GET deployment requests method. For the results of one batch request, the GET pipeline requests method may be used.

The following actions are also permitted for batch requests:

  • Retrieve multiple batch deployment and pipeline requests: Retrieve the results of multiple batch requests in one call. This method takes in a list of the request id's.
  • Delete multiple batch deployment and pipeline requests: Delete the multiple batch requests in one call. This method takes in a list of the request id's. All batch requests that were not yet 'completed' or 'failed' are terminated.
  • List all batch deployment and pipeline requests: Give an overview of all batch requests for a deployment or pipeline. Selection and sorting options are available.
  • Delete a single batch deployment and pipeline request: Delete a single batch request and terminate it.

Request Schedules

To make periodic requests to deployments and pipelines, you can use the Request Schedule functionality. See Request Schedules for more information.

Request examples

We can imagine it can be a bit tricky to figure out how to make a request from the framework you are using. To help you out we have collected a few examples here for various languages.

# Using the Python Client Library
import ubiops
client = ubiops.ApiClient(ubiops.Configuration(api_key={"Authorization": API_TOKEN}))
api = ubiops.CoreApi(client)

data = {'input_field_1': 123}
# A direct request to the default version
request_result = api.deployment_requests_create(
    project_name=PROJECT_NAME,
    deployment_name=DEPLOYMENT_NAME,
    data=data
)
print(request_result)

# Using a 'raw' HTTP request
import requests

# You can copy the endpoint URL from the WebApp or look up the format on Swagger
receive = requests.post("<your endpoint url>/requests", 
    json = {'input field 1': 123}, 
    headers={'Authorization':'your API token'})
print(receive.json()['result']) 
# Using the R Client Library
Sys.setenv(UBIOPS_PROJECT = "<YOUR_PROJECT_NAME>")
Sys.setenv(UBIOPS_API_TOKEN = "Token <YOUR_API_TOKEN>")
library(ubiops)

input_data <- list(input_field_1 = 123)

result <- deployment_requests_create(
    deployment.name = DEPLOYMENT_NAME,
    data = input_data
)
print(result)

# Using a 'raw' HTTP request
content_type <- httr::content_type_json()
body <- rjson::toJSON(list(input_field_1 = 123))
headers <- httr::add_headers(Authorization="Token <YOUR_API_TOKEN>")
r <- httr::POST("<your endpoint url>/requests", headers, content_type, body = body, encode = "json")
content <- httr::content(r, "text", encoding = "UTF-8")
print(content)
// Helper function for posting a request
async function postRequest(url = "", data = {}) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: API_TOKEN,
    },
    body: JSON.stringify(data),
  });
  return response.json();
}

// Using the postRequest function
postRequest(
  `<your endpoint url>/requests`,
  { input_field_1: 123 }
).then((response) => doSomethingWith(response))

Making a direct request to a pipeline:

# Using the Python Client Library
import ubiops
client = ubiops.ApiClient(ubiops.Configuration(api_key={"Authorization": API_TOKEN}))
api = ubiops.CoreApi(client)

data = {'input_field_1': 123}
request_result = api.pipeline_requests_create(
    project_name=PROJECT_NAME,
    pipeline_name=PIPELINE_NAME,
    data=data
)
print(request_result)

# Using a 'raw' HTTP request
import requests

# You can copy the endpoint URL from the WebApp or look up the format on Swagger
receive = requests.post("<your endpoint url>/requests", 
    json = {'input field 1': 123}, 
    headers={'Authorization':'your API token'})
print(receive.json()['result']) 
# Using the R Client Library
Sys.setenv(UBIOPS_PROJECT = "<YOUR_PROJECT_NAME>")
Sys.setenv(UBIOPS_API_TOKEN = "Token <YOUR_API_TOKEN>")
library(ubiops)

input_data <- list(input_field_1 = 123)

result <- pipeline_requests_create(
    pipeline.name = PIPELINE_NAME,
    data = input_data
)
print(result)

# Using a 'raw' HTTP request
content_type <- httr::content_type_json()
body <- rjson::toJSON(list(input_field_1 = 123))
headers <- httr::add_headers(Authorization="Token <YOUR_API_TOKEN>")
r <- httr::POST("<your endpoint url>/requests", headers, content_type, body = body, encode = "json")
content <- httr::content(r, "text", encoding = "UTF-8")
print(content)
// Helper function for posting a request
async function postRequest(url = "", data = {}) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: API_TOKEN,
    },
    body: JSON.stringify(data),
  });
  return response.json();
}

// Using the postRequest function
postRequest(
  `<your endpoint url>/requests`,
  { input_field_1: 123 }
).then((response) => doSomethingWith(response))