Standardized Response Schema

Overview

To ensure consistency across the Supervised AI platform, all endpoints in the testing-api adhere to a standardized JSON response schema. This structure allows client-side applications to predictably parse data, handle errors, and manage state regardless of the specific resource being accessed.

Response Structure

Every API response consists of a root object containing a status indicator, a data payload or error details, and optional metadata.

Field Definitions

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Indicates if the request was processed successfully. | | data | object \| array \| null | The primary resource(s) requested. Returns null if an error occurs. | | message | string | A human-readable summary of the result or error. | | errors | array \| null | An optional list of specific validation or logic errors. | | meta | object | Optional metadata, such as pagination details or rate limiting info. |

Success Responses

A successful request (typically HTTP 200 OK or 201 Created) will always return success: true.

Single Resource

Used when fetching a specific entity by ID or performing a single-action update.

{
  "success": true,
  "message": "Resource retrieved successfully",
  "data": {
    "id": "test_99ab12",
    "name": "Model_Validation_Suite",
    "status": "completed",
    "accuracy": 0.98
  },
  "errors": null
}

Collection with Metadata

Used for list endpoints. The meta object provides context for pagination.

{
  "success": true,
  "message": "Tests retrieved successfully",
  "data": [
    { "id": "1", "name": "Standard_Test" },
    { "id": "2", "name": "Edge_Case_Test" }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 10,
    "total_pages": 15
  }
}

Error Responses

When a request fails (HTTP 4xx or 5xx), the success field is set to false. The errors array provides granular details for debugging or UI form validation.

Validation Error (HTTP 422)

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    {
      "field": "model_id",
      "code": "required",
      "detail": "The model_id field cannot be empty."
    },
    {
      "field": "sample_rate",
      "code": "out_of_range",
      "detail": "Sample rate must be between 0 and 1."
    }
  ]
}

Authentication/General Error (HTTP 401/500)

{
  "success": false,
  "message": "Unauthorized access. API key is missing or invalid.",
  "data": null,
  "errors": null
}

Implementation Guidelines

• Consistency: Do not omit the data key even if the response is empty; return an empty array [] or null instead.
• HTTP Status Codes: The JSON success boolean should always mirror the HTTP status class (e.g., 2xx = true, 4xx/5xx = false).
• Metadata: Use the meta object for information that is not part of the core resource but is necessary for processing the response (e.g., request IDs for tracing).