Versioning and changelog
Every Nebbos API surface is versioned in the URI prefix. Change classification (safe within a version, or requiring a new version) is contract-defined rather than discretionary. Deprecated versions remain in parallel operation for a minimum of twelve months before retirement.
Version prefix
Versions are URI-prefixed: /api/v1/, /api/v2/, and so on. Two consecutive major versions are supported concurrently. Deprecated versions continue to serve for at least twelve months following the deprecation announcement.
New endpoints are added under the current prefix. Existing endpoints continue serving under their prefix through the formal deprecation timeline specified in Deprecation policy.
Safe changes within a version
Within a version prefix, the following changes are contract-permitted:
- Addition of new endpoints
- Addition of new optional fields to request or response shapes
- Addition of new enumerated values to fields explicitly declared “forward-compatible” in the OpenAPI specification
- Addition of new request and response headers
- Loosening of validation (accepting inputs previously refused)
- Improvement of error messages while preserving the machine-readable
codefield
None of the above break a client that ignores fields not addressed in the client’s schema.
Changes that require a new version
The following changes ship as /api/vN+1:
- Removal of an endpoint
- Removal of a field from a response
- Change to a field’s type or shape
- Tightening of validation (refusing inputs previously accepted)
- Change to the semantics of an existing operation
- Change to an authentication requirement — for example, a Guest-tier endpoint elevated to Host tier
Version vN continues to serve for a minimum of twelve months from the date vN+1 is published.
Client implementations must ignore unknown fields. Client-side validation asserting that a response contains only known fields is contract-incompatible; the platform adds fields freely within a version.
Changelog
The dated version-change record is served at:
https://api.nebbos.ai/api/v1/changelog # human-readable
https://api.nebbos.ai/api/v1/changelog.json # machine-readableEach entry names the change, the affected endpoints, and the version in which it lands. Breaking-change entries carry a link to the corresponding migration guide referenced from Deprecation policy.