/raida-objects

POST ASYNC

Creates, updates (put), or removes (rm) a file object on the RAIDA filesystem.

POST /api/v1/raida-objects

Alias: /manage-raida-filesystem

Description

This endpoint allows you to manage individual file objects. Use the put command to create a new file or overwrite an existing one with new data. Use the rm command to delete a file.

Asynchronous Operation

Both commands are asynchronous. They return a task ID immediately, and you can poll the /tasks/{id} endpoint to check for completion.

Request Body

Parameter	Type	Required	Description
`command`	string	Yes	The command to execute: `"put"` or `"rm"`.
`path`	string	Yes	The full path of the file on the RAIDA filesystem.
`data`	string	For `put`	Base64-encoded string of the file content. Required only for the "put" command.

Response (in completed task `data`)

A successful task for either `put` or `rm` will contain an empty or simple success object in its `data` field (e.g., {"status": "success"}).

Examples

JavaScript: Manage RAIDA Objects

const apiHost = 'http://localhost:8006';

async function pollTask(taskId, command) {
    const taskResponse = await fetch(`${apiHost}/api/v1/tasks/${taskId}`);
    const taskData = await taskResponse.json();
    const task = taskData.payload;

    console.log(`[${command}] Task ${taskId} progress: ${task.progress}% - ${task.message}`);

    if (task.status === 'completed') {
        console.log(`[${command}] Task finished successfully!`, task.data);
        return true; // Stop polling
    } else if (task.status === 'error') {
        console.error(`[${command}] Task failed:`, task.message);
        return true; // Stop polling
    }
    return false; // Continue polling
}

async function raidaObjectCommand(payload) {
    try {
        const response = await fetch(`${apiHost}/api/v1/raida-objects`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
        });
        const taskInfo = await response.json();
        const taskId = taskInfo.payload.id;
        console.log(`[${payload.command}] Task created with ID: ${taskId}`);

        const pollInterval = setInterval(async () => {
            const isDone = await pollTask(taskId, payload.command);
            if (isDone) clearInterval(pollInterval);
        }, 2000);
    } catch (error) {
        console.error(`Failed to start ${payload.command} task:`, error);
    }
}

// Example Usage:
// raidaObjectCommand({ command: "put", path: "/usr/myname/message.txt", data: btoa("Data to be stored") });
// raidaObjectCommand({ command: "rm", path: "/usr/myname/old_message.txt" });

cURL: Put Object

# Step 1: Initiate the put task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/raida-objects" \
-H "Content-Type: application/json" \
-d '{"command":"put", "path":"/usr/myname/message.txt", "data":"SGVsbG8gU0tZ"}' | jq -r '.payload.id')
echo "put task started with ID: $TASK_ID"

# Step 2: Poll the task endpoint
while true; do
  RESPONSE=$(curl -s "http://localhost:8006/api/v1/tasks/$TASK_ID")
  STATUS=$(echo $RESPONSE | jq -r '.payload.status')
  echo "Polling task.. Status: $STATUS"; if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "error" ]]; then
    echo "Final Response:"; echo $RESPONSE | jq; break
  fi; sleep 2
done

cURL: Remove Object

# Step 1: Initiate the rm task
TASK_ID=$(curl -s -X POST "http://localhost:8006/api/v1/raida-objects" \
-H "Content-Type: application/json" \
-d '{"command":"rm", "path":"/usr/myname/message.txt"}' | jq -r '.payload.id')
echo "rm task started with ID: $TASK_ID"

# Step 2: Poll the task endpoint
while true; do
  RESPONSE=$(curl -s "http://localhost:8006/api/v1/tasks/$TASK_ID")
  STATUS=$(echo $RESPONSE | jq -r '.payload.status')
  echo "Polling task.. Status: $STATUS"; if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "error" ]]; then
    echo "Final Response:"; echo $RESPONSE | jq; break
  fi; sleep 2
done

Go: Manage RAIDA Objects

package main
import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"
)

const apiHost = "http://localhost:8006/api/v1"

type RaidaObjectRequest struct {
	Command string `json:"command"`
	Path    string `json:"path"`
    Data    string `json:"data,omitempty"`
}

type TaskResponse struct {
	Payload struct {
		ID       string      `json:"id"`
		Status   string      `json:"status"`
		Progress int         `json:"progress"`
		Message  string      `json:"message"`
		Data     interface{} `json:"data"`
	} `json:"payload"`
}

func pollTask(taskId, command string) {
	for {
		resp, err := http.Get(fmt.Sprintf("%s/tasks/%s", apiHost, taskId))
		if err != nil {
			log.Printf("Error polling task: %v\n", err)
			return
		}
		var taskResp TaskResponse
		json.NewDecoder(resp.Body).Decode(&taskResp)
		resp.Body.Close()

		fmt.Printf("[%s] Polling... Status: %s\n", command, taskResp.Payload.Status)

		if taskResp.Payload.Status == "completed" {
			fmt.Printf("[%s] Task completed. Result: %+v\n", command, taskResp.Payload.Data)
			return
		} else if taskResp.Payload.Status == "error" {
			fmt.Printf("[%s] Task failed: %s\n", command, taskResp.Payload.Message)
			return
		}
		time.Sleep(2 * time.Second)
	}
}

func raidaObjectCommand(payload RaidaObjectRequest) {
	requestBody, _ := json.Marshal(payload)
	resp, err := http.Post(fmt.Sprintf("%s/raida-objects", apiHost), "application/json", bytes.NewBuffer(requestBody))
    if err != nil {
		log.Fatalf("Failed to start %s task: %v", payload.Command, err)
	}
	defer resp.Body.Close()

	var taskResp TaskResponse
	json.NewDecoder(resp.Body).Decode(&taskResp)

	fmt.Printf("[%s] Task created with ID: %s\n", payload.Command, taskResp.Payload.ID)
	pollTask(taskResp.Payload.ID, payload.Command)
}

func main() {
    // Example 1: Put an object
    // putPayload := RaidaObjectRequest{Command: "put", Path: "/usr/myname/message.txt", Data: "RGF0YSB0byBiZSBzdG9yZWQ="}
    // raidaObjectCommand(putPayload)

    // Example 2: Remove an object
    rmPayload := RaidaObjectRequest{Command: "rm", Path: "/usr/myname/message.txt"}
    raidaObjectCommand(rmPayload)
}