Response Schema Design

Overview

The testing-api follows a strict, predictable JSON response pattern to ensure consistency across the Supervised AI platform's testing suite. By standardizing the response envelope, clients can implement a single parsing logic to handle both successful data retrieval and error states.

All responses are returned as standard JSON objects with a consistent top-level structure.

Base Response Envelope

Every API response contains a primary envelope that distinguishes between a successful operation and an error state.

{
  "success": boolean,
  "timestamp": "ISO-8601-String",
  "data": object | array | null,
  "error": object | null
}

Top-Level Fields

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Indicates if the request was processed successfully without business logic errors. | | timestamp | string | The UTC timestamp of the response generation in ISO-8601 format. | | data | object | array | The actual payload of the response. This is null if success is false. | | error | object | Contains error details. This is null if success is true. |

Success Response Schema

When an operation is successful, the data field contains the requested resources. Depending on the endpoint, this will be either a single object or an array of objects.

Single Resource Example

Used for fetching specific test cases or configuration details.

{
  "success": true,
  "timestamp": "2023-10-27T10:00:00Z",
  "data": {
    "test_id": "test_9921",
    "status": "completed",
    "accuracy_score": 0.98,
    "runtime_ms": 150
  },
  "error": null
}

Collection/List Example

Used for listing test runs or available models.

{
  "success": true,
  "timestamp": "2023-10-27T10:05:00Z",
  "data": [
    { "id": "model_v1", "version": "1.0.2" },
    { "id": "model_v2", "version": "2.1.0" }
  ],
  "error": null
}

Error Response Schema

In the event of a failure (validation errors, authentication issues, or internal server errors), the success field is set to false, and the error object provides context.

Error Object Structure

| Field | Type | Description | | :--- | :--- | :--- | | code | string | A machine-readable string identifying the error type (e.g., VALIDATION_FAILED). | | message | string | A human-readable description of the error. | | details | object | (Optional) Key-value pairs providing specific context, such as field-level validation errors. |

Example Error Response

{
  "success": false,
  "timestamp": "2023-10-27T10:10:00Z",
  "data": null,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The provided test parameters are invalid.",
    "details": {
      "batch_size": "Value must be between 1 and 100",
      "model_id": "Model ID not found"
    }
  }
}

Testing Metadata

For long-running test executions or high-volume datasets, the API includes a metadata object within the data payload to handle pagination and execution telemetry.

Pagination Schema

When requesting lists, the response includes a _meta key within the data object:

{
  "success": true,
  "data": {
    "items": [...],
    "_meta": {
      "total_count": 500,
      "page": 1,
      "limit": 20,
      "has_next": true
    }
  }
}

Execution Telemetry

For testing endpoints, additional execution metadata is often provided:

| Field | Type | Description | | :--- | :--- | :--- | | trace_id | string | Unique identifier for the test execution trace. | | environment | string | The testing environment used (e.g., sandbox, production-mirror). | | latency_breakdown | object | Internal processing times for different stages of the test. |

Implementation Notes

• HTTP Status Codes: While the success boolean provides logic-level feedback, the API consistently uses standard HTTP status codes (2xx for success, 4xx for client errors, 5xx for server errors).
• Null Values: Fields with no data are generally returned as null rather than being omitted, ensuring consistent object shapes for client-side type definitions.
• Content-Type: All responses are served with Content-Type: application/json.