# Web4Strategy API versioning and deprecation policy

## Current version

The current public REST API version is `1`. Canonical resources remain under `/api/` and are versioned with the optional `X-Web4Strategy-API-Version` request header. Omitting the header selects the current version. Successful API responses include `X-Web4Strategy-API-Version: 1`.

The supported value is:

```http
X-Web4Strategy-API-Version: 1
```

An unsupported value returns HTTP `400` with a typed JSON error containing `error`, `message`, `resolution`, and `statusCode` fields. The stable error code is `UNSUPPORTED_API_VERSION`.

## Deprecation signals

Web4Strategy will not silently remove or change a documented API version. If a version is deprecated, responses for that version will include:

- `Deprecation: true`
- `Sunset: <HTTP-date>` with the planned retirement date
- a link to updated migration documentation in the response or this policy

The project’s default notice period is at least 90 days between the first deprecation signal and retirement. The current version `1` is not deprecated.

## Schemas and compatibility

The OpenAPI document at `/openapi.json` is the source of truth for request parameters, response schemas, and typed 4xx/5xx errors. Additive fields may be introduced within a version. Removing fields, changing field types, changing error codes, or changing endpoint semantics requires a new version or a published migration notice.

## Rate limits

Responses expose `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until reset), and `RateLimit-Policy`. The legacy `X-RateLimit-*` headers remain available for compatibility. HTTP `429` responses include `Retry-After` in seconds.