Terminate an Instance

Terminate an Instance - Overview

The Yotta Series Terminate Instance API allows authenticated users to permanently terminate a Yotta Series pod using its instance ID.

The endpoint accepts an instance_id in the JSON request body and terminates the specified pod along with all its associated data. The response includes a descriptive message and the result of the operation.

Important: Terminating an instance permanently deletes the pod and all associated data. Verify the instance ID and back up any required data before submitting the request.

Endpoint

Property	Value
HTTP Method	`POST`
Endpoint	`/yotta/delete`
Full URL	`https://cloud.dataoorts.com/api/v1/yotta/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 Yotta Series instance to terminate.

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

Example Request Body

{
  "instance_id": 4
}

Replace 4 with the ID of the Yotta Series instance you want to terminate.

Request Examples

cURL - Use the following command to terminate a Yotta Series instance:

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

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

Python Example Implementation

The following example uses the requests library to terminate a Yotta 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/yotta/delete"


def delete_yotta_instance(
    api_key: str,
    instance_id: int,
) -> dict | None:
    """
    Permanently terminate a Yotta Series pod.

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

    Returns:
        The JSON response containing the termination result,
        or None if the API returns a non-JSON response.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the JSON response 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():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_yotta_instance(
            api_key=api_key,
            instance_id=4,
        )

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

    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 yotta_delete.py

Windows PowerShell

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

Script submits instance ID & displays the returned status and message when a valid JSON response is received.

Example Success Response

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

{
  "message": "Instance 4 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 the API request. A successful response returns `success`.
`message`	String	A descriptive message confirming the termination result.

Understanding Instance Information

Instance Termination

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

When the API returns "status": "success", the response indicates that the termination operation was successful. The message field provides confirmation text and identifies the instance in the example response.

Associated Data

Terminating an instance permanently deletes the pod and all its associated data. Back up any required data before submitting the termination request.

Important Notes

1. Permanent Deletion: Terminating a Yotta pod permanently terminates the pod & deletes all associated data.

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

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

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

5. Response Validation: Check the returned status and message fields to understand the operation result.

6. Request Timeout: If a request times out, verify the instance information before retrying the termination request because 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. The example also checks the response content type and handles JSON decoding errors before processing the 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 the `instance_id` identifies the intended Yotta pod.
HTTP request fails	Catch `requests.exceptions.RequestException` and inspect the error details.
Request times out	Check instance info 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 the JSON decoding error before accessing response fields.

Get Help and Support

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