Civic Data

Versioning and deprecation

A surface that does not change without warning.

Agents should be able to integrate against Civic Data without surprises. This page is the commitment for the REST API, the MCP tools and the CLI.

REST

  • The major version is in the URL path: /v1/…. Breaking changes ship only under a new prefix (/v2/).
  • Additive changes — new endpoints, new optional parameters, new response fields, new notices — may ship inside a major version without notice. Clients must ignore unknown fields.
  • Response schemas are published in the OpenAPI document and generated from the same Zod contracts the gateway validates against.

Deprecation signals

  • When an endpoint, parameter or major version is scheduled for removal, its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers and a Link header with rel="deprecation" pointing at the migration note.
  • The minimum notice between the first Sunset header and removal is 90 days.
  • Deprecated OpenAPI operations are marked deprecated: true, and deprecated MCP tools say so in their description.

MCP and CLI

  • MCP tool names and input schemas follow the same additive rule. A renamed tool keeps the old name, marked deprecated, for the notice period. The server reports its version in serverInfo (currently civic-data-london 0.1.0).
  • The civicdata npm package uses semantic versioning; a breaking CLI change is a major release.

Data semantics

A change to a calculation, join or classification is a data-semantics change, not an API change. It is recorded in the methodology and decision records, shipped with tests, and the edge cache version is incremented so old responses are never reused.

Current API version: 0.1.0. Questions: contact Civic Data.