theme

2026-01-05 15:41:31 +01:00
parent 67e51a5348
commit 2d81f78fed
3 changed files with 349 additions and 147 deletions
--- a/doc/api.md
+++ b/doc/api.md
@@ -1,48 +1,130 @@
 # TestArena API Reference

+TestArena provides a RESTful API for programmatic job submission and status monitoring.
+
 ## Base URL
-`http://<server-ip>:8080/api`
+
+All API endpoints are prefixed with `/api`.
+
+```
+http://<your-server>/api
+```
+
+## Authentication
+
+The API uses Basic Authentication. You must provide your username and password in the request body for job submission.

 ## Endpoints

-### 1. Submit a New Queue
-`POST /queue`
-Submits a new set of tasks to the execution queue.
-**Payload:**
+### 1. Submit Job
+
+Submit a new test job to the queue.
+
+-   **URL**: `/submit_job`
+-   **Method**: `POST`
+-   **Content-Type**: `application/json`
+
+#### Request Body
+
+| Field | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `username` | string | Yes | Your TestArena username |
+| `password` | string | Yes | Your TestArena password |
+| `branch_name` | string | Yes | Git branch name to test |
+| `scenarios` | array | Yes | List of scenario names to execute |
+
+#### Example Request
+
+```bash
+curl -X POST http://localhost:5000/api/submit_job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "your_password",
+    "branch_name": "feature/new-driver",
+    "scenarios": ["adc_init_test", "gpio_init_test"]
+  }'
+```
+
+#### Success Response
+
+**Code**: `200 OK`
+
 ```json
 {
-    "source": "branch_name",
-    "job_id": [
-        "environment",
-        {
-            "task_id": "scenario_path"
-        }
-    ]
+  "success": true,
+  "job_id": 123,
+  "status": "waiting",
+  "remote_triggered": true,
+  "message": "Job submitted successfully"
 }
 ```

-### 2. Get Status
-`GET /status/{id}`
-Gets the status of a specific queue or task.
+#### Error Response

-### 3. Abort Queue or Task
-`POST /abort/{id}`
-Aborts a waiting or running queue or a single task.
+**Code**: `401 Unauthorized`

-### 4. Delete Queue
-`DELETE /delete/{id}`
-Permanently deletes a queue and its associated data.
+```json
+{
+  "error": "Invalid credentials"
+}
+```

-## Local API (Web App)
+**Code**: `400 Bad Request`

-### Get Job Details
-`GET /jobs/{job_id}`
+```json
+{
+  "error": "Missing required fields: username, password, branch_name, scenarios"
+}
+```

-### Get Job Status (Triggers Update)
-`GET /jobs/{job_id}/status`
+---

-### Abort Job
-`POST /jobs/{job_id}/abort`
+### 2. Get Job Status

-### Delete Job
-`POST /jobs/{job_id}/delete`
+Retrieve the status and details of a specific job.
+
+-   **URL**: `/job/<job_id>`
+-   **Method**: `GET`
+
+#### URL Parameters
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `job_id` | integer | Yes | The ID of the job to retrieve |
+
+#### Example Request
+
+```bash
+curl http://localhost:5000/api/job/123
+```
+
+#### Success Response
+
+**Code**: `200 OK`
+
+```json
+{
+  "job_id": 123,
+  "status": "in_progress",
+  "branch_name": "feature/new-driver",
+  "scenarios": ["adc_init_test", "gpio_init_test"],
+  "remote_results": {
+    "adc_init_test": ["PASS", "http://.../report.html"],
+    "gpio_init_test": ["FAIL", "http://.../report.html"]
+  },
+  "created_at": "2023-10-27T10:00:00",
+  "completed_at": null,
+  "remote_queue_id": "123"
+}
+```
+
+#### Error Response
+
+**Code**: `404 Not Found`
+
+```json
+{
+  "error": "Job not found"
+}
+```