API Versioning

SemVer per plugin, deprecation lifecycle, sunset headers, and the public deprecation registry

Every nself plugin exposes a versioned HTTP API. Version numbers follow Semantic Versioning. Deprecated endpoints are announced via standard HTTP headers and a public registry so clients can migrate before removal.

Where the Version Lives

Each plugin carries its API version in two places:

plugin.json: the "api_version" field in the plugin manifest
cli/internal/deprecation/registry.yaml: the ecosystem-wide registry read by the CLI

Version Policy

Change type	Bump
New endpoint added	Patch (`1.0.0` → `1.0.1`)
Endpoint behavior changed, backward-compatible	Minor (`1.0.0` → `1.1.0`)
Endpoint deprecated	Minor (grace period opens)
Endpoint removed after grace period	Major (`1.x.x` → `2.0.0`)

Deprecation Lifecycle

The endpoint gets deprecated_in: <version> in registry.yaml.

Every response from that path includes:

Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT

After the removed_in version ships, the path returns 410 Gone.

HTTP Headers

Both headers follow open standards:

Header	Standard	Value
`Deprecation`	RFC 8594	`true`
`Sunset`	RFC 8594	RFC-1123 UTC date

CLI Tooling

# Check all plugins for deprecated endpoints
nself api deprecation-check

# Check a single plugin
nself api deprecation-check --plugin ai

# View the deprecation calendar for a plugin
nself api changelog ai

# Strict mode (exits 1 on any BREAKING entry, use in CI)
nself api deprecation-check --strict

When nself start detects a deprecated endpoint in an installed plugin, it prints:

[API WARNING] plugin 'ai' v1.1.0: endpoint '/v1/complete' was deprecated in v1.2.0,
removed in v2.0.0. Use '/v2/complete' instead.

Public Registry

The full deprecation registry is published at:

GET https://ping.nself.org/api/deprecation-registry.json

{
  "schema_version": "1",
  "generated_at": "2026-04-23T00:00:00Z",
  "lts_baseline": "1.0.9",
  "lts_window_end": "2027-04-17",
  "plugins": [
    {
      "name": "ai",
      "api_version": "1.3.0",
      "deprecated_endpoints": []
    }
  ]
}

The Admin UI at http://localhost:3021/api/versioning provides a searchable table view of this registry.

CI Gate

The api-compat.yml workflow in plugins-pro blocks pull requests that add a new HTTP endpoint without a deprecation grace period on any replaced endpoint. To override, a reviewer adds the breaking-change-approved label, which is audited in the next release notes.