Long Running Operations

Overview

In some cases, you might need to perform bulk operations that take a significant amount of time to complete. To ensure a smooth and efficient process, our APIs handle these operations asynchronously.

Asynchronous Bulk APIs

When you trigger a long-running operation via our bulk APIs, such as the Bulk Assign Set API, the server will not keep the connection open until the operation is complete. Instead, it will return an immediate response indicating that the operation has been accepted for processing.

Expected Response

Upon initiating a long-running operation, you will receive an HTTP 202 Accepted response. This status code indicates that the request has been received and understood, and that the processing is continuing asynchronously.

Response Body

The response body will contain a URL that you can use to check the status and retrieve the results of the operation. This URL is specific to the operation you initiated and will provide updates on its progress.

Example Response:

{
  "location": "https://api.sensos.io/v1/accounts/2ce1a86e-7331-4542-b1f8-085ac1225cff/operations/ed37a334-ca01-4bb3-9139-f2892915a306"
}

Fetching Operation Results

To check the status of your long-running operation, make a GET request to the provided location. This will return information about the current status of the operation and, once completed, the results of the operation.

Example Status Check Request:

GET https://api.sensos.io/v1/accounts/2ce1a86e-7331-4542-b1f8-085ac1225cff/operations/ed37a334-ca01-4bb3-9139-f2892915a306

Example Status Check Response:

{
  "id": "e49c730d-30ef-459d-af71-fef960b17033",
  "status": "Running",
  "type": "DeviceSetAssignment"
}

Once the operation is complete, the status will change to Completed.

Example Completed Response:

{
  "id": "e49c730d-30ef-459d-af71-fef960b17033",
  "status": "Completed",
  "type": "DeviceSetAssignment"
}

Error Handling

If there are any issues with the operation, the status endpoint will return appropriate error messages and status codes. Make sure to handle these scenarios in your implementation.

Example Error Response:

{
  "id": "e49c730d-30ef-459d-af71-fef960b17033",
  "status": "Failed",
  "type": "DeviceSetAssignment",
  "error": {
  	"id": "e5eba106-0faa-44cb-a8c7-38b2ebf45328",
    "message": "Failed to assign some of the labels to the Set",
    "code": "FailedAssigningLabelsToSet",
    "details": {
    	"id": "2495e243-1d57-44ae-bebc-31622ceb59c5",
      "message": "Device 1234567 is not exists",
      "code": "DeviceNotExists"
    }
  }
}

Best Practices

• Polling Frequency: Avoid excessive polling. Implement an exponential backoff strategy to check the operation status.
• Error Handling: Implement robust error handling to manage various status responses and errors.
• Timeouts: Set appropriate timeouts for your requests to avoid hanging operations in your application.