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
successboolean 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
nullrather than being omitted, ensuring consistent object shapes for client-side type definitions. - Content-Type: All responses are served with
Content-Type: application/json.