Versioning Policy

Versioning Strategy

The testing-api follows Semantic Versioning 2.0.0 (SemVer). This ensures that integrations with the Supervised AI platform remain stable while allowing for the continuous delivery of new features and improvements.

Version numbers are expressed as MAJOR.MINOR.PATCH:

• MAJOR: Incremented when we make incompatible API changes (e.g., removing a field or changing a required data type).
• MINOR: Incremented when we add functionality in a backwards-compatible manner (e.g., adding an optional field or a new endpoint).
• PATCH: Incremented when we make backwards-compatible bug fixes or documentation improvements.

Breaking Changes

To ensure stability for developers, breaking changes are only introduced in Major version updates. A change is considered "breaking" if it:

• Removes or renames an existing endpoint.
• Removes or renames a field in a request or response body.
• Changes a field from optional to required.
• Changes the data type of a field.
• Changes error codes or authentication requirements.

Version Access

Clients can specify the desired version of the API structure through the URL path. This ensures that your integration does not break when a new Major version is released.

GET /api/v1/testing/schema
Host: api.supervised.ai

If no version is specified (where applicable), the API defaults to the latest stable version. However, it is strongly recommended to explicitly pin your version in production environments.

Deprecation Policy

When a new Major version is released, the previous version enters a Deprecation Period.

1. Announcement: We notify users via the documentation and platform dashboard.
2. Support: The deprecated version continues to receive critical security patches for 6 months.
3. Sunset: After 6 months, the version is officially retired and will return a 410 Gone status code.

Deprecation Headers

API responses for deprecated versions will include a Warning header to alert developers:

HTTP/1.1 200 OK
Warning: 299 - "The v1 API is deprecated and will be removed on 2024-12-31. Please migrate to v2."

Backward Compatibility

The following changes are considered backward-compatible and may occur within Minor or Patch releases:

• Adding new API endpoints.
• Adding new optional request parameters.
• Adding new properties to existing JSON response objects.
• Changing the order of properties in a JSON response.
• Fixing typos in descriptions or internal logic that does not affect output format.