# Andrew Campi API versioning and deprecation policy

The portfolio API is versioned in the URL path. The current version is `/api/v1`. This page is the deprecation policy agents can rely on. Every API response points here with `Link: <https://andrewcampi.com/api-versioning.html>; rel="describedby"`.

## Current version

`/api/v1` is the supported version. It is not deprecated. Responses do not include a `Deprecation` header or a `Sunset` header, because no removal date has been set. Adding a field to a JSON object is not a breaking change. Removing a field, renaming a field, or changing the meaning of a status code is a breaking change, and that kind of change will be published as `/api/v2` rather than edited into `/api/v1`.

The machine-readable contract for the current version is the [OpenAPI specification](https://andrewcampi.com/openapi.json). The guide that lists the operations is [Andrew Campi developer resources](https://andrewcampi.com/developers.html).

## How a version is retired

When a version is scheduled for removal, both of the following happen at least six months before the last day it will respond:

- This page names the version, the replacement URL, and the last day.
- Responses from that version include `Deprecation: true` and a `Sunset` header. The `Sunset` value is the HTTP-date of that last day, as defined by RFC 8594.

Until this page names a sunset date, keep calling `/api/v1`. No version of this API is deprecated today.