Skip to content

Making requests

Deployments and pipelines in UbiOps receive data through their REST API endpoints. One request triggers a single run of the code inside the deployment.

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

Request types

There are 2 types of requests: direct and batch requests.

  • Direct requests take a single data payload and keep a connection open during processing, after which the result is returned immediately. It is synchronous.

  • Batch requests are asynchronous. They require two API calls to send the data and retrieve the results. A batch request can take up to 250 data payloads simultaneously, for each of them a separate request_id is returned with which the results can be retrieved at a later time.

What type of request you can create for your deployment or pipeline is determined by the deployment mode of the respective deployment version or pipeline objects. A batch deployment version only allows batch requests, where an express deployment version allows only direct requests.

For a pipeline it works a little different, as pipelines are made up of several deployments. If a pipeline contains only express deployments, you can send both direct and batch requests to that pipeline. If the pipeline contains at least one batch deployment though, it can only handle batch requests.

Request timeouts

Every request has a configurable timeout parameter, which indicates the time after which the request is automatically aborted. This is a great way to terminate code or connections that may hang unexpectedly. The value for the timeout of a request depends on the type of request and for what type of object the request is made. In the table below you can see the range of the different timeout ranges and their default values.

Please take into account that the timeout includes the full request duration as well as the time it takes for an instance to initialize and start up (a cold start).

Request Type Object Type Default timeout Minimum timeout Maximum timeout
Direct Deployment 300 seconds 10 seconds 3600 seconds
Direct Pipeline 3600 seconds 10 seconds 7200 seconds
Batch Deployment 14400 seconds 10 seconds 172800 seconds
Batch Pipeline 14400 seconds 10 seconds 172800 seconds

Request Schedules

It is also possible to schedule requests instead of triggering them with an API call. To make periodic requests to deployments and pipelines, you can use the Request Schedule functionality. See Request Schedules for more information.

Deployment Requests using the WebApp

You can easily make 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.

create

You can test your deployment by creating a 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 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 immediately if your deployment is of express type. A batch request will be visible in the requests overview page of the version, if the retention mode of the version is set to metadata or full. During processing of the batch request, the request is visible in the requests overview page, as it is required for the UbiOps platform to be able to process a request.

Deployment Requests using the API

Each deployment, pipeline and their versions get unique API endpoints when created. You can use these endpoints to make requests with data to process.

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.

API endpoints for making requests

Deployment API endpoints:

  • The direct request endpoint for deployments is used to send one data payload to the deployment. Available for deployments with both structured as plain input.
    URL format: https://api.ubiops.com/v2.1/projects/{project_name}/deployments/{deployment_name}/requests
  • The batch request endpoint for deployment allows sending multiple data payloads to the deployment. Available for deployments with both structured as plain input.
    URL format: https://api.ubiops.com/v2.1/projects/{project_name}/deployments/{deployment_name}/requests/batch

Pipeline API endpoints:

  • The direct request endpoint for pipelines is used to send one data payload to the pipeline. Available for pipelines with both structured as plain input.
    URL format: https://api.ubiops.com/v2.1/projects​/{project_name}​/pipelines​/{pipeline_name}​/requests
  • The batch request endpoint for pipelines allows sending multiple data payloads to the pipeline. Available for pipeline with both structured as plain input.
    URL format: https://api.ubiops.com/v2.1/projects​/{project_name}​/pipelines​/{pipeline_name}​/requests/batch

Making requests to specific deployment or pipeline versions

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, you can use:

For a full list of available API endpoints related to requests in UbiOps, please see our Swagger page.

Data payload for the API request

To make a request you need to use the correct endpoint specifying the deployment or pipeline and request type (see above) and include the request data payload in the body.

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.

Below you can see an example of how to format the request data payload for a direct request with a structured input format.

{
  "input-field-1": 5.0,
  "input-field-2": "N",
  "input-field-3": [0.25, 0.25, 2.1, 16.3]
}
Ane example of a succesful response of a direct requests looks like:
{
  "id": "ffce45da-1562-419a-89a0-0a0837e55392",
  "deployment": "deployment-1",
  "version": "v2",
  "success": true,
  "result": {
    "output-field-1": "2.1369",
    "output-field-2": "5.5832",
  },
  "error_message": null
}

A failed deployment request looks like:

{
  "id": "85ae32a7-fe3a-4a55-be27-9db88ae68501",
  "deployment": "deployment-1",
  "version": "v1",
  "success": false,
  "result": None,
  "error_message": "Asset ID not supported"
}

A pipeline request will return you the result including all results and error messaged of the intermediate steps as in:

{
  "id": "286f771b-6617-4985-ab49-12ed720e62b1",
  "pipeline": "pipeline-1",
  "version": "v1",
  "success": false,
  "error_message": "Error while processing a deployment request",
  "deployment_requests": [
    {
      "id": "a7524614-bdb7-41e1-b4c1-653bb72c30b4",
      "pipeline_object": "deployment-object-1",
      "success": true,
      "error_message": null
    },
    {
      "id": "fe322c50-58f8-4e67-b7d6-cba14273874e",
      "pipeline_object": "deployment-object-2",
      "success": false,
      "error_message": "Invalid message format" 
    }
  ],
  "result": {
    "output_field": 23.5
  }
}

In case a deployment expects plain input data, a single string or list of string input is required that will be sent as-is to the deployment. In case of a batch request, a list of string input is required.

Sending files (blobs) as part of the payload

If your deployment expects a file (blob) field as input, you have to provide the id of the blob in the input. The blob first needs to be uploaded through the blob API endpoint before making the request. Read the page on file (blob) handling for more information.

{
  "input-field-1": 5.0,
  "blob-input-field": "f52ff875-4980-4d71-9798-a469ef8cece2"
}

For more information and to try things out, you can visit our Swagger page.

Retrieving batch request results

The result of a direct request is always immediate, meaning that the result is returned in the API call response 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 in the body:

[
  {
    "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. Therefore you need to regularly poll the API endpoint to check if the request has finished processing.

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 deployment batch request, you can use the GET deployment requests method. URL format: https://api.ubiops.com/v2.1/projects/{project_name}/deployments/{deployment_name}/requests/collect

  • For the results of one pipeline batch request, the GET pipeline requests method may be used. URL format: https://api.ubiops.com/v2.1/projects/{project_name}/pipelines/{pipeline_name}/requests/collect

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 examples

Because it might be difficult to figure out how to make a request from the framework you are using, we have collected a few examples here for various languages.

Below you can check some examples for creating a direct request to the default version of a deployment and to a pipeline.

API endpoints

See the above paragraph on API endpoints to find the right endpoint URLs to use with the examples below.

Making a direct request to the default version of a deployment with the Python or R client library:

# 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 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)

The same, now using generic methods:

# 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("<deployment endpoint url>/requests", 
    json = {'input field 1': 123}, 
    headers={'Authorization':'your API token'})

print(receive.json()['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("<deployment 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(
  `<deployment endpoint url>/requests`,
  { input_field_1: 123 }
).then((response) => doSomethingWith(response))

Making a direct request to the default version of a pipeline with the Python or R client library:

# 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 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)

The same, now using generic methods:

# 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(
    url='<pipeline endpoint url>/requests', 
    json={'input field 1': 123}, 
    headers={'Authorization':'your API token'}
)

print(receive.json()['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("<pipeline 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(
  `<pipeline endpoint url>/requests`,
  { input_field_1: 123 }
).then((response) => doSomethingWith(response))