> ## Documentation Index
> Fetch the complete documentation index at: https://team.k0labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> API versioning strategy and best practices

> 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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

| Field       | Description                                               |
| ----------- | --------------------------------------------------------- |
| `code`      | Warning type: `DEPRECATED_FIELD` or `DEPRECATED_ENDPOINT` |
| `message`   | Human-readable description of the deprecation             |
| `field`     | The deprecated field name (for field deprecations)        |
| `sunset`    | ISO 8601 date when the feature will be removed            |
| `migration` | URL to migration documentation                            |

## Endpoint Deprecation Example

When an entire endpoint is deprecated:

```json theme={null}
{
  "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.