Documentation

API Versioning

AegisGate uses URL-based API versioning. All endpoints are prefixed with /api/v{N}/ where {N} is the major version number.

Current version: v1 (stable since 3.0.0)

Examples:

  • GET /api/v1/compliance/scan
  • POST /api/v1/compliance/report?framework=atlas
  • GET /api/v1/compliance/integrity
  • GET /api/v1/sla

Stability Guarantees

GuaranteeScopeDetails
No breaking changes within v1EndpointsAll v1 endpoints maintain backward compatibility
Additive onlyFieldsNew fields may be added to responses; clients must ignore unknown fields
Deprecated fieldsFieldsDeprecated fields are maintained for at least 2 minor versions (6+ months)
HTTP status codesResponsesStatus codes will not change for existing error conditions
Rate limitingHeadersX-RateLimit-* headers are contractually stable

What Counts as a Breaking Change

A breaking change is any change that would cause a correctly-implemented client to fail:

  • Removing an endpoint
  • Removing a response field
  • Changing a field type (string → number, etc.)
  • Changing an HTTP method (GET → POST)
  • Changing a URL path segment
  • Changing error response structure
  • Increasing required parameters

What Does NOT Count as a Breaking Change

  • Adding a new response field (clients must ignore unknowns)
  • Adding a new endpoint
  • Adding a new optional query parameter
  • Adding a new enum value (clients must handle unknown values)
  • Changing documentation or error messages
  • Reordering JSON object keys

Deprecation Policy

  1. Announcement: Deprecated features are announced in release notes and via Deprecation HTTP headers
  2. Grace period: At least 2 minor versions (6+ months) after announcement
  3. Removal: Only in a new major version (v2)
  4. Migration guide: Provided for all breaking changes

Release Cadence

Release TypeCadenceBreaking Changes
Patch (3.8.x)WeeklyNever
Minor (3.x.0)MonthlyNever
Major (x.0.0)Quarterly (estimated)Only on major bump

API Endpoint Stability Matrix

EndpointVersionStatusSince
GET /api/v1/compliance/healthv1✅ Stable3.0.0
GET /api/v1/compliance/scanv1✅ Stable3.0.0
GET /api/v1/compliance/reportv1✅ Stable3.0.0
GET /api/v1/compliance/integrityv1✅ Stable3.8.0
GET /api/v1/slav1✅ Stable3.0.0
POST /v1/scanv1✅ Stable3.0.0

Version Negotiation

Clients should:

  1. Use the Accept header to request a specific version: Accept: application/json; version=1
  2. Handle unknown response fields gracefully (RFC 7231)
  3. Monitor Deprecation and Sunset response headers
  4. Check the X-API-Version response header for the current version

Contact

For API versioning questions, open an issue at github.com/aegisgatesecurity/aegisgate-platform or email security@aegisgate.dev