add docs

doc/api_reference.md

@@ -0,0 +1,111 @@
+# API Reference
+
+The TestArena Backend provides a RESTful API for managing test queues and monitoring system status.
+
+## Base URL
+`http://<server-ip>:8080/api`
+
+---
+
+## Endpoints
+
+### 1. Submit a New Queue
+`POST /queue`
+
+Submits a new set of tasks to the execution queue.
+
+**Request Body:**
+```json
+{
+    "source": "string",
+    "<queue_id>": [
+        "environment_name",
+        {
+            "<task_id>": "path/to/scenario.xml"
+        }
+    ]
+}
+```
+
+**Response:**
+```json
+{
+    "status": "Queue OK",
+    "queue_id": "string"
+}
+```
+
+---
+
+### 2. List All Queues
+`GET /queues`
+
+Returns a list of all queues in the system, ordered by creation date (newest first).
+
+**Response:**
+```json
+[
+    {
+        "id": "string",
+        "status": "Waiting|Running|Finished|Aborted",
+        "created_at": "ISO8601 Timestamp",
+        "environment": "string",
+        "source": "string"
+    }
+]
+```
+
+---
+
+### 3. Get Status
+`GET /status/{id}`
+
+Gets the status of a specific queue or task.
+
+**Response:**
+```json
+{
+    "id": "string",
+    "type": "queue|task",
+    "status": "string"
+}
+```
+
+---
+
+### 4. Abort Queue or Task
+`POST /abort/{id}`
+
+Aborts a waiting or running queue or a single task.
+
+**Response:**
+```json
+{
+    "id": "string",
+    "status": "Aborted"
+}
+```
+
+---
+
+### 5. Delete Queue
+`DELETE /delete/{id}`
+
+Permanently deletes a queue, its associated tasks, and all related files from the server.
+
+**Response:**
+```json
+{
+    "id": "string",
+    "status": "Deleted"
+}
+```
+
+---
+
+## Error Handling
+
+The API uses standard HTTP status codes:
+*   `200 OK`: Request successful.
+*   `404 Not Found`: The requested ID does not exist.
+*   `500 Internal Server Error`: An unexpected error occurred on the server.