Contribution Guidelines

Proposing Changes to the API Structure

We welcome contributions that improve the clarity, efficiency, and coverage of the Supervised AI testing API. To ensure consistency across the platform, please follow these guidelines when proposing changes to endpoints or response formats.

Core Principles

• Predictability: Responses should follow the established nested structure.
• Explicit Versioning: Any breaking changes to the structure must be proposed with a versioning strategy (e.g., /v1/ to /v2/).
• Standardized Status Codes: Use standard HTTP status codes (200 for success, 400 for client errors, 422 for validation errors, etc.).

Proposing a New Endpoint

When adding a new endpoint to the structure, provide a clear definition of the request parameters and the expected successful response.

Example Proposal Format:

### POST /v1/test-suite/evaluate
**Description**: Triggers a batch evaluation for a specific model.

**Input (JSON):**
{
  "model_id": "string",
  "dataset_id": "string",
  "config": {
    "threshold": "float"
  }
}

**Output (202 Accepted):**
{
  "job_id": "uuid",
  "status": "queued",
  "eta": "string (ISO 8601)"
}

Response Format Standards

All new additions to the API must adhere to the standard JSON response wrapper used throughout the Supervised AI platform.

Success Responses

Data should be wrapped in a data object. If the response involves a list, include a meta object for pagination.

{
  "data": {
    "id": "123",
    "type": "evaluation",
    "attributes": {
      "score": 0.95,
      "status": "completed"
    }
  }
}

Error Responses

Errors must provide a machine-readable code and a human-readable message.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The 'model_id' field is required.",
    "details": [
      { "field": "model_id", "reason": "missing" }
    ]
  }
}

Contribution Workflow

1. Open an Issue: Before making structural changes, open an issue to discuss the proposed modification. This ensures the change aligns with the broader Supervised AI roadmap.
2. Branching: Create a feature branch using the naming convention feat/api-<endpoint-name> or fix/api-<issue-number>.
3. Update Documentation: Ensure that the corresponding Markdown files or OpenAPI/Swagger definitions in this repository are updated to reflect the changes.
4. Submit a Pull Request:
   • Provide a clear summary of what changed.
   • Include a "Before" and "After" example for any changes to existing response formats.
   • Tag the relevant internal stakeholders for review.

Review Criteria

The maintainers will review your PR based on:

• Consistency: Does it match the existing naming conventions (e.g., snake_case)?
• Completeness: Are all possible status codes (401, 403, 404) documented?
• Utility: Does the change provide necessary data for the frontend or SDK consumers?