Skip to main content
Strategies for evolving the API without breaking changes, deprecation standards, and stability commitments
The k0rdent API uses URL-path versioning to ensure stability and provide clear upgrade paths for API clients.

​
Version Format

All API endpoints include the version in the URL path using the /v1/ prefix: 
# Atlas APIs (api.internal.example.com)
https://api.internal.example.com/v1/region/global/infrastructure/servers
https://api.internal.example.com/v1/region/global/compute/clusters
https://api.internal.example.com/v1/region/global/organizations

# Arc APIs (api.example.com)
https://api.example.com/v1/region/{region}/projects
https://api.example.com/v1/region/{region}/compute/clusters
https://api.example.com/v1/region/{region}/stacks

# Shared Services (both domains)
/v1/region/global/auth
/v1/region/global/notifications
/v1/region/global/webhooks
The version is part of the URL path, making it explicit and unchangeable for each request.

​
Version Policy

k0rdent follows these versioning principles:

​
Major Versions Only

  • Version identifiers use major version numbers only: v1, v2, etc.
  • No minor version numbers in the URL (e.g., no v1.1 or v1.2)
  • Breaking changes require a new major version

​
Feature Flags Over Minor Versions

Instead of minor versions, new features are:
  • Added to existing versions in a backward-compatible way
  • Controlled via feature flags when necessary
  • Announced through deprecation warnings in responses

​
No Version in Response

The API version is not included in response bodies. The URL path is the authoritative source of the version being used. 
{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
    // No "apiVersion" field - use the URL path
  }
}

​
Deprecation Timeline

When features or endpoints need to be deprecated:
  1. 6-month notice period - Deprecation announcements provide at least 6 months notice before removal
  2. Warning headers - Deprecated endpoints return warnings in the meta.warnings array
  3. Migration guides - Documentation links provided for upgrading to new patterns

​
Deprecation Warning Format

Deprecated endpoints or fields include warnings in the response: 
{
  "success": true,
  "data": {
    "id": "srv_abc123",
    "name": "node-01",
    "bmcAddress": "ipmi://10.0.100.50"
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z",
    "warnings": [
      {
        "code": "DEPRECATED_FIELD",
        "field": "bmcAddress",
        "message": "bmcAddress is deprecated, use bmc.address instead",
        "sunset": "2026-06-01",
        "migration": "https://docs.k0rdent.io/migration/bmc-fields"
      }
    ]
  }
}

​
Warning Object Fields

FieldDescription
codeWarning type: DEPRECATED_FIELD or DEPRECATED_ENDPOINT
messageHuman-readable description of the deprecation
fieldThe deprecated field name (for field deprecations)
sunsetISO 8601 date when the feature will be removed
migrationURL to migration documentation

​
Endpoint Deprecation Example

When an entire endpoint is deprecated: 
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z",
    "warnings": [
      {
        "code": "DEPRECATED_ENDPOINT",
        "message": "This endpoint is deprecated. Use /v2/servers instead.",
        "sunset": "2026-06-01",
        "migration": "https://docs.k0rdent.io/migration/v2-servers"
      }
    ]
  }
}

​
Best Practices

​
For API Consumers

  • Monitor warning arrays - Check meta.warnings in responses and log them
  • Plan migrations early - Don’t wait until the sunset date
  • Use version pinning - Explicitly specify the version in all requests
  • Test new versions - When a new major version is released, test in a staging environment

​
For API Producers

  • Maintain backward compatibility - Within a major version, never break existing clients
  • Provide clear migration paths - Include detailed migration guides
  • Give advance notice - Minimum 6 months for deprecations
  • Support multiple versions - Keep at least two major versions active during transitions

​
Upgrading to a New Version

When a new major version is released:
  1. Review the changelog and migration guide
  2. Test the new version in a development or staging environment
  3. Update your API base URL to use the new version
  4. Monitor for any deprecation warnings in the new version
  5. Gradually roll out the change to production
The k0rdent API maintains stable major versions to give you confidence when building integrations.