API Versioning

API Versioning

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

1. The endpoint gets deprecated_in: <version> in registry.yaml.
2. Every response from that path includes:

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

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

See Also

• nself api CLI reference
• Admin UI
• Deprecation Registry endpoint