Skip to content

API.md

Latest commit

 

History

History
425 lines (338 loc) · 6.57 KB

API.md

File metadata and controls

425 lines (338 loc) · 6.57 KB
Raw

OpenTester REST API Documentation

OpenTester provides REST API for Web UI usage. MCP tools are the primary interface, REST API is auxiliary.

Basic Information

  • Base URL: http://localhost:8000/api
  • Content-Type: application/json
  • CORS: Allow http://localhost:5173

Health Check

GET /health

Check service health status.

Response:

{
  "status": "ok",
  "service": "opentester"
}

Project Management

GET /projects

List all projects.

Response:

[
  {
    "id": "uuid",
    "name": "Project Name",
    "target": {"type": "cli"},
    "created_at": "2026-02-27T10:00:00Z",
    "updated_at": "2026-02-27T10:00:00Z"
  }
]

POST /projects

Create new project.

Request Body:

{
  "name": "New Project",
  "target": {"type": "cli"},
  "prd_content": "Optional PRD content"
}

Response:

{
  "id": "uuid",
  "name": "New Project",
  "target": {"type": "cli"},
  "created_at": "2026-02-27T10:00:00Z",
  "updated_at": "2026-02-27T10:00:00Z"
}

GET /projects/{project_id}

Get project details.

Response:

{
  "id": "uuid",
  "name": "Project Name",
  "target": {"type": "cli"},
  "cases": {
    "case-uuid": {
      "id": "case-uuid",
      "name": "Test Case",
      "created_at": "2026-02-27T10:00:00Z"
    }
  },
  "created_at": "2026-02-27T10:00:00Z",
  "updated_at": "2026-02-27T10:00:00Z"
}

PUT /projects/{project_id}

Update project.

Request Body:

{
  "name": "Updated Name",
  "target": {"type": "api", "base_url": "http://localhost:3000"}
}

DELETE /projects/{project_id}

Delete project.

Response: 204 No Content

Test Case Management

GET /cases/{project_id}

Get all cases for a project.

Response:

{
  "cases": {
    "case-uuid": {
      "id": "case-uuid",
      "name": "Test Case",
      "dsl_content": "version: '1.0'\n...",
      "created_at": "2026-02-27T10:00:00Z",
      "updated_at": "2026-02-27T10:00:00Z"
    }
  }
}

POST /cases/{project_id}

Create new test case.

Request Body:

{
  "name": "New Test Case",
  "dsl_content": "version: '1.0'\nmeta:\n  name: Test\nsteps: []"
}

Response:

{
  "id": "case-uuid",
  "name": "New Test Case",
  "dsl_content": "...",
  "created_at": "2026-02-27T10:00:00Z",
  "updated_at": "2026-02-27T10:00:00Z"
}

PUT /cases/{project_id}/{case_id}

Update test case.

Request Body:

{
  "name": "Updated Name",
  "dsl_content": "updated dsl content"
}

DELETE /cases/{project_id}/{case_id}

Delete test case.

Response: 204 No Content

Test Execution

POST /execution/run/{project_id}/{case_id}

Execute single test case.

Response:

{
  "execution_id": "exec-uuid",
  "status": "running"
}

POST /execution/run-project/{project_id}

Execute entire project.

Request Body (optional):

{
  "case_ids": ["case-1", "case-2"]
}

Response:

{
  "execution_id": "exec-uuid",
  "status": "running"
}

GET /execution/status/{execution_id}

Get execution status.

Response:

{
  "execution_id": "exec-uuid",
  "status": "completed",
  "result": {
    "success": true,
    "steps": [
      {
        "name": "Step 1",
        "status": "completed",
        "output": "..."
      }
    ]
  }
}

POST /execution/stop/{execution_id}

Stop execution.

Response:

{
  "success": true,
  "message": "Execution stopped"
}

GET /execution/log/{execution_id}

Get execution logs.

Response:

{
  "execution_id": "exec-uuid",
  "logs": [
    {
      "timestamp": "2026-02-27T10:00:00Z",
      "level": "info",
      "message": "Starting execution"
    }
  ]
}

GET /execution/history/{project_id}

Get project execution history.

Response:

{
  "executions": [
    {
      "execution_id": "exec-uuid",
      "case_id": "case-uuid",
      "status": "completed",
      "created_at": "2026-02-27T10:00:00Z",
      "updated_at": "2026-02-27T10:01:00Z"
    }
  ]
}

WebSocket

WS /ws

Real-time execution updates.

Connection: ws://localhost:8000/ws

Message Format:

{
  "type": "execution_update",
  "data": {
    "execution_id": "exec-uuid",
    "status": "running",
    "current_step": 2,
    "total_steps": 5
  }
}

Template Management

GET /templates

List all templates.

Query Parameters:

  • category - Filter by category
  • target_type - Filter by target type
  • tag - Filter by tag

Response:

[
  {
    "id": "template-uuid",
    "name": "Template Name",
    "description": "Description",
    "target_type": "cli",
    "category": "api",
    "tags": ["tag1", "tag2"],
    "usage_count": 5,
    "created_at": "2026-02-27T10:00:00Z"
  }
]

POST /templates

Create template.

Request Body:

{
  "name": "New Template",
  "description": "Template description",
  "dsl_template": "version: '1.0'\n...",
  "target_type": "cli",
  "category": "api",
  "tags": ["tag1"]
}

GET /templates/{template_id}

Get template details.

Response:

{
  "id": "template-uuid",
  "name": "Template Name",
  "description": "Description",
  "dsl_template": "version: '1.0'\n...",
  "target_type": "cli",
  "category": "api",
  "tags": ["tag1"],
  "variables": [
    {
      "name": "base_url",
      "description": "API base URL",
      "required": true,
      "default_value": "http://localhost:8000"
    }
  ],
  "created_at": "2026-02-27T10:00:00Z"
}

POST /templates/{template_id}/instantiate

Create case from template.

Request Body:

{
  "project_id": "project-uuid",
  "case_name": "New Test Case",
  "variables": {
    "base_url": "http://localhost:3000"
  }
}

Response:

{
  "case_id": "case-uuid",
  "name": "New Test Case",
  "message": "Case created from template"
}

Error Handling

Error Response Format

{
  "detail": "Error message"
}

HTTP Status Codes

Status Code Description
200 Success
201 Created successfully
204 Deleted successfully
400 Bad request parameters
404 Resource not found
422 Validation error
500 Internal server error

Relationship with MCP

REST API is mainly for Web UI, MCP tools are for Agent integration.

Feature REST API MCP Tool
Project Management ✅ ✅
Test Case Management ✅ ✅
Test Execution ✅ ✅
DSL Validation ❌ ✅
Template Management ✅ ✅

Recommendations:

  • Agents use MCP tools
  • Web UI uses REST API
  • Complex operations (e.g., DSL validation) use MCP