Terminate an Instance

Terminate an Instance - Overview

The Terminate an Instance API allows you to terminate an Orix Series instance using its Local Instance ID or DC Provider Instance ID.

The API accepts the instance_id parameter as either an integer representing the instance's local database ID or a string representing the DC provider's instance ID.

Important: Termination is a destructive operation. Verify the instance identifier before submitting the request.

Endpoint

Property	Value
Method	`DELETE`
Endpoint	`/api/v1/orix/instances`
Base URL	`https://cloud.dataoorts.com`
Content-Type	`application/json`
Authentication	Bearer API token

Full URL:

DELETE https://cloud.dataoorts.com/api/v1/orix/instances

Authentication

Include your Dataoorts API key in the Authorization header using the Bearer authentication scheme.

Authorization: Bearer YOUR_API_KEY

You can obtain your API key from the Dataoorts Unify API.

Request Parameters

The API expects a JSON request body containing the identifier of the instance to terminate.

Parameter	Type	Required	Description
`instance_id`	Integer or String	Yes	The local database ID or DC Provider Instance ID of the instance to terminate.

Example request body:

{
  "instance_id": 4
}

You can also provide the DC Provider's Instance ID as a string:

{
  "instance_id": "dc_provider_instance_vid"
}

Replace the example value with the identifier of the instance you want to terminate.

Request Examples

cURL - Use the following command to delete the Orix Instance.

curl -X DELETE "https://cloud.dataoorts.com/api/v1/orix/instances" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": 4}'

Python Example Implementation

The following Python example uses an environment variable for the API key, sends a DELETE request, and handles HTTP and JSON parsing errors.

import os
import json
import requests
from typing import Any

BASE_URL = "https://cloud.dataoorts.com/api/v1"
API_KEY = os.getenv("DATAOORTS_API_KEY")


def terminate_orix_instance(instance_id: int | str) -> dict[str, Any]:
    """
    Terminate an Orix Series instance.

    Args:
        instance_id: Local database instance ID or provider instance ID.

    Returns:
        The parsed JSON response from the API.

    Raises:
        ValueError: If the API key is not configured.
        requests.RequestException: If the HTTP request fails.
        ValueError: If the response is not valid JSON.
    """
    if not API_KEY:
        raise ValueError(
            "DATAOORTS_API_KEY environment variable is not set."
        )

    url = f"{BASE_URL}/orix/instances"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"instance_id": instance_id}

    try:
        response = requests.delete(
            url,
            headers=headers,
            json=payload,
            timeout=60,
        )
        response.raise_for_status()

        try:
            data = response.json()
        except requests.exceptions.JSONDecodeError as exc:
            raise ValueError(
                "The API returned an invalid JSON response."
            ) from exc

        print(json.dumps(data, indent=4))
        return data

    except requests.RequestException as exc:
        print(f"Failed to terminate Orix instance: {exc}.")
        raise


if __name__ == "__main__":
    # Replace 456 with the intended instance's ID.
    terminate_orix_instance(456)

Set your API key as an environment variable before running the script.

Linux or macOS:

export DATAOORTS_API_KEY="YOUR_API_KEY"

Windows PowerShell:

$env:DATAOORTS_API_KEY="YOUR_API_KEY"

Example Success Response

A successful request returns a JSON response similar to the following:

{
  "current_status": "terminated",
  "message": "Ins 456 Terminated.",
  "status": "success"
}

The message and instance identifier will depend on the instance being terminated.

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API operation. The provided success response returns `"success"`.
`message`	String	A message describing the termination result.
`current_status`	String	The instance status returned by the API. The example response returns `"terminated"`.

Understanding the Response

Successful Termination

When the API returns "status": "success" and "current_status": "terminated", the response indicates that the instance has been terminated.

Instance Identifier

The message field identifies the instance referenced in the response. Check this identifier against your intended target when reviewing the result.

Important Notes

Use the DELETE HTTP method to terminate an Orix Series instance.
The endpoint is https://cloud.dataoorts.com/api/v1/orix/instances.
Provide instance_id in the JSON request body.
The instance_id value can be an integer local database ID or a string DC Provider Instance ID/VID, as supported by the supplied API example.
Verify the instance identifier before making the request because termination is a destructive operation.
Keep your API key private & store it securely in an env variable rather than hardcoding it in your code.

Error Handling

Your integration should handle request failures and unexpected responses appropriately.

Scenario	Recommended Handling
API key is missing	Set the `DATAOORTS_API_KEY` environment variable.
HTTP request fails	Catch `requests.RequestException` exception & inspect error.
Response contains invalid JSON	Handle the JSON parsing error before processing the response.
Response indicates success	Check returned `status`, `current_status`, and `message` fields.

The Python example uses response.raise_for_status() to detect unsuccessful HTTP status codes and validates that the response can be parsed as JSON. Refer to the actual API response for further details when troubleshooting a failed request.

Get Help and Support

For assistance with the Orix Series API, contact the Dataoorts support team at [email protected].