Terminate an Instance

Terminate an Instance - Overview

The Atlas Series Terminate Instance API allows authenticated users to permanently delete an Atlas Series instance using its instance ID.

The endpoint accepts an instance_id in the JSON request body and terminates the specified instance. The response includes the current instance status, a descriptive message, and the result of the operation.

Important: Terminating an instance permanently deletes the instance and all associated data. Verify the instance ID before submitting the request.

Endpoint

Property	Value
HTTP Method	`POST`
Endpoint	`/atlas/delete`
Full URL	`https://cloud.dataoorts.com/api/v1/atlas/delete`
Authentication	Bearer Token
Request Format	JSON
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The endpoint requires a JSON request body containing the ID of the Atlas Series instance to terminate.

Parameter	Type	Required	Description
`instance_id`	Integer	Yes	The identifier of the Atlas Series pod to terminate.

Example Request Body

{"instance_id": 10}

Replace 10 with the ID of the instance you want to terminate.

Request Examples

cURL - Use the following command to terminate an Atlas Series pod:

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/atlas/delete" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 10
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key and 10 with the intended instance ID.

Python Example Implementation

The following example uses the requests library to terminate an Atlas Series instance. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks the response format before processing the returned data.

Install the required dependency:

pip install requests

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/atlas/delete"


def delete_atlas_instance(
    api_key: str,
    instance_id: int,
) -> dict:
    """
    Permanently terminate an Atlas Series instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The ID of the Atlas instance to terminate.

    Returns:
        dict: The JSON response containing the termination result.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response is not JSON or cannot be decoded.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "instance_id": instance_id,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        raise ValueError(
            "The API returned a non-JSON response: "
            f"{response.text[:500]}"
        )

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


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = delete_atlas_instance(
            api_key=api_key,
            instance_id=10,
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))
        print("Current Status:", result.get("current_status"))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid API response: {exc}.")

Set your API key before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python atlas_delete.py

Windows PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python atlas_delete.py

The script submits the instance ID and displays the returned status, message, and current instance status.

Example Success Response

A successful request returns a JSON object containing the current instance status, a descriptive message, and the response status.

HTTP Status: 200 OK

{
  "current_status": "terminated",
  "message": "Instance 10 terminated successfully.",
  "status": "success"
}

The instance ID and response message may differ depending on the instance being terminated.

Response Fields

Field	Type	Description
`status`	String	Indicates result of API request. Successful response returns `success`.
`message`	String	A descriptive message confirming the termination result.
`current_status`	String	The current pod status retrned by API. Example returns `terminated`.

Understanding Instance Information

Instance Termination

The instance_id identifies the Atlas Series instance targeted by the request.

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

Associated Data

Terminating an instance permanently deletes the instance and all associated data. Ensure that any required data has been backed up before submitting the termination request.

Important Notes

1. Permanent Deletion: Terminating an Atlas Container permanently deletes the pod and all associated data.

2. Instance ID: Provide a valid instance_id in the JSON request body.

3. Verify Before Termination: Confirm that the pod ID identifies correct instance before submitting the request.

4. HTTP Method: Use the POST method with the /api/v1/atlas/delete endpoint.

5. Response Validation: Check the returned status, current_status, and message fields to understand the termination result.

6. Request Timeout: If a request times out, verify the instance status before attempting another termination request. The result of the original request may be uncertain.

7. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

If the request fails, the API may return an unsuccessful HTTP status code or a response that does not match the expected JSON format.

Your application should handle authentication failures, invalid instance IDs, network errors, request timeouts, server errors, and unexpected response formats. Error codes and messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes, Example also checks response content type & handles JSON decoding errors before processing termination result.

Scenario	Recommended Handling
API key is missing	Set the `DATAOORTS_API_KEY` environment variable.
Authentication fails	Verify that the API key is valid and included in the `Authorization` header.
Instance ID is invalid	Verify that `instance_id` identifies the intended Atlas instance.
HTTP request fails	Catch `requests.exceptions.RequestException` and inspect the error details.
Request times out	Check the instance status before retrying the termination request.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle JSON decoding error before accessing response fields.

Get Help and Support

For assistance with Atlas instance termination or API integration, Contact support team at [email protected].