Endpoint Standardization

Overview

To ensure consistency, scalability, and ease of integration across the Supervised AI platform, all endpoints in the testing-api must adhere to the following standardization guidelines. These standards govern how resources are named, how HTTP methods are applied, and how URL paths are structured.

URL Structure

All API endpoints must follow a hierarchical structure based on resources rather than actions.

Base URL and Versioning

All requests are prefixed with a version identifier to ensure backward compatibility as the platform evolves.

https://api.supervised.ai/testing/v1/

Resource Pathing

• Nouns over Verbs: Use plural nouns to describe resources (e.g., /test-cases instead of /getTestCases).
• Kebab-case: Use lowercase letters and hyphens for multi-word path segments.
• Hierarchy: Nest resources to show relationships.

Example Structure: GET /projects/{project_id}/test-suites/{suite_id}/executions

HTTP Methods

The API utilizes standard HTTP verbs to define the action being performed on a resource.

| Method | Usage | Success Code | | :--- | :--- | :--- | | GET | Retrieve a resource or a collection of resources. | 200 OK | | POST | Create a new resource or trigger a specific process (e.g., starting an execution). | 201 Created | | PUT | Replace an existing resource entirely. | 200 OK | | PATCH | Partially update an existing resource. | 200 OK | | DELETE | Remove a resource. | 204 No Content |

Naming Conventions

Path Parameters

Path parameters should be descriptive and use snake_case.

• Correct: /test-runs/{run_id}
• Incorrect: /test-runs/{id} (Too ambiguous in nested contexts)

Query Parameters

Query parameters are used for filtering, sorting, and pagination. Use camelCase for query keys.

• GET /executions?projectId=123&status=failed&limit=10

JSON Property Naming

Both request bodies and response payloads must use snake_case for all keys to maintain consistency with the platform's data models.

{
  "execution_id": "exec_8821",
  "is_automated": true,
  "started_at": "2023-10-27T10:00:00Z"
}

Standard Request/Response Format

Content Type

All requests that include a body must set the Content-Type header to application/json. All responses will return application/json.

Successful Response Wrapper

For collection endpoints, the API returns a standardized object to support pagination.

{
  "data": [
    { "id": "tc_01", "name": "Login Test" },
    { "id": "tc_02", "name": "Signup Test" }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 20
  }
}

Error Handling

Errors are returned with a consistent structure and appropriate HTTP 4xx or 5xx status codes.

| Code | Meaning | | :--- | :--- | | 400 | Bad Request (Validation failed) | | 401 | Unauthorized (Invalid API Key) | | 403 | Forbidden (Insufficient permissions) | | 404 | Not Found (Resource does not exist) |

Error Body Example:

{
  "error": {
    "code": "validation_failed",
    "message": "The field 'priority' is required.",
    "details": [
      {
        "field": "priority",
        "issue": "must_not_be_null"
      }
    ]
  }
}

Implementation Example

The following example demonstrates a standardized endpoint for creating a new test execution.

Endpoint: POST /v1/test-suites/{suite_id}/executions

Request Headers:

Content-Type: application/json
Authorization: Bearer <api_token>

Request Body:

{
  "execution_name": "Regression Run - Sprint 42",
  "environment": "staging",
  "tags": ["critical", "ui"]
}

Response (201 Created):

{
  "id": "exec_9901",
  "status": "queued",
  "created_at": "2023-10-27T14:30:00Z"
}