# API Deprecation Policy

> Applies to the Robust Devs Content API. Specification: https://robustdevs.co/openapi.json

## Versioning

Canonical paths are versioned in the URL: `/api/v1/...`.

The unversioned `/api/...` paths are stable aliases of the same handlers. They are not deprecated and are not scheduled for removal, but new integrations should use `/api/v1/`.

Every response carries an `API-Version` header naming the version that served it.

## What counts as breaking

Breaking changes ship under a **new path version** (`/api/v2/`). A published version is never changed in place.

| Change | Breaking? | Ships as |
| --- | --- | --- |
| Removing a field or endpoint | Yes | New path version |
| Renaming a field | Yes | New path version |
| Narrowing a type or an accepted value | Yes | New path version |
| Changing an `error.code` value | Yes | New path version |
| Adding an optional field | No | In place |
| Adding a new endpoint | No | In place |
| Adding a new `error.code` | No | In place |

## How deprecation is signalled

When a version is scheduled for removal:

1. Its responses begin carrying the **`Deprecation`** header (RFC 9745) with the date deprecation took effect.
2. Its responses carry a **`Sunset`** header (RFC 8594) with the date the version stops responding.
3. A `Link` header with `rel="successor-version"` points at the replacement.

```
Deprecation: @1780000000
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: </api/v2/blogs>; rel="successor-version"
```

## Minimum notice

**At least 180 days** between the first `Deprecation` header and the `Sunset` date.

## Current status

**No version is deprecated.** `v1` is current and carries no `Deprecation` or `Sunset` header. If you are reading those headers programmatically and seeing none, that is the expected state, not a missing implementation.

## Contact

Questions about a migration: hi@robustdevs.co