Files
radicle-explorer/explorer/docs/adr/0001-expand-and-contract-api-changes.md
T
Daniel Norman d8f363ca99 Replace API version checks with feature detection
httpd:
- Serve the API at /api, not only under /v1
- Keep serving it at /api/v1, without a redirect, until the first
  major release after explorer and the Open Graph worker switch
  to /api
- Remove apiVersion: released explorers do not read it
- Add `httpd.releases` to `/info`, set by the artifacts feature

explorer:
- Remove the API version check, its config and the unused
  compare-versions dependency
- Keep the node version in a plain parse error message
- Add `minimumSupportedVersion`, set to 0.28.0, and warn on nodes
  whose major is older, treating 0.y as the major before 1.0
- Do not warn on builds without a release number
- Show a warning on the node page of an outdated node
- Mark an outdated node in the seed picker on every page
- Name the node version and the floor in parse errors
- Drop the `/node` fallback for httpd without `/info`, which
  predates the floor
- Check the status, not `ResponseError`, so the Open Graph worker
  can import compat without the fetcher
- Name the httpd release each shim serves, not a date
- Drop the mime shim for httpd 0.18.1 and the unused `lib/file.ts`
- Read the node from `/info` in repo views
- Pass the node and its features to repo views as one `node` param
- Show the releases tab and pages when the node supports releases,
  and the counter only when there is a count
- Read a release count as release support on older httpd
- Test the flag and the fallback

docs:
- Restructure docs/api-changes.md: the supported versions, one
  table of removals, fixed fields per change, and a link to ADR
  0001 for the rules
- Say in ADR 0001 that each compat comment names what the other
  side does
- Say in ADR 0001 when a capability needs a flag in /info

tests:
- Run e2e tests on httpd 0.30.0, above the floor, instead of 0.26.0
- Run the release tests on it too, so they cover the compat shims
- Skip only those that need release counts per scope on it
- Test a node without release support through a mocked `/info`
  flag, instead of an httpd that predates the floor
2026-10-29 18:32:03 +01:00

4.5 KiB

1. Expand and contract httpd API changes

Date: 2026-10-20

Status

Accepted

Context

Explorer is deployed continuously, and the public instance at radicle.network always runs the latest version. The seeds it reads (httpd instances) upgrade on their own schedule, so explorer often reads an older httpd. A change to a response can break explorer on those seeds, and the operator of a seed cannot tell why their node no longer loads.

Decision

One version. httpd uses semantic versions. The version covers the HTTP API, the CLI and the config. A minor release adds, and a major release removes or changes. Before 1.0, 0.y counts as the major, as in Cargo: a release that only adds bumps 0.y.z to 0.y.(z+1), and a release that removes or changes bumps it to 0.(y+1).0.

Supported releases. Explorer supports every httpd release from minimumSupportedVersion in http-client/lib/compat.ts up to the latest. This can span more than two majors, because before 1.0 each 0.y is a major. Explorer warns about a node older than that. It does not warn about a version that it cannot parse, such as pre-release or nix-<commit>. httpd does not warn its operator at startup: it cannot know the floor of the explorer that reads it.

The 3-month guideline. Explorer aims to support a major for at least three months after the next major replaces it. The release that bumps the major writes this target date in docs/api-changes.md, the only place that holds dates. When the date comes, check which versions the seeds run, then raise minimumSupportedVersion or move the date. You may raise it sooner, when few seeds still run that major or when a fix needs it.

Expand, then contract. A breaking change ships in two steps:

  1. Expand, in a minor release: httpd adds the new fields next to the old ones, and keeps the old ones exactly as they were. The client reads the new fields and falls back to the old ones.
  2. Contract, in a later major release: httpd removes the old fields. It may not remove a field or path that the explorer client or the Open Graph worker (workers/open-graph) still reads.

A security fix is the one exception: it may narrow an existing field in place, for example to stop it from sending data that an attacker can write. It must keep the field's type, so that older clients still parse it. Its release notes say which field changed and why.

One place for compatibility code. The client turns the responses of every supported httpd release into one shape. Version-specific code lives in http-client/lib/compat.ts. A fallback to an older endpoint stays in the client method that calls that endpoint.

Name the side and the version in every removal. httpd and the client remove their compatibility code at different times, so each compat comment says what the other side does, which side it is on, and when it can go:

// Compat: older clients ... Server: remove in a major release.
// Compat: older httpd ... Client: remove when explorer drops httpd 0.30.

Track every change in one place. docs/api-changes.md lists each change with its expand release, the consumers that read it, and its pending removals. A release fills its ## API changes notes from this list.

Feature detection, not version checks. The client learns what a seed supports from the seed itself. It never branches on the httpd version, and uses that version only to warn about an unsupported node. The signal depends on the feature:

  • A feature that every build has: a field that is present, or an endpoint that answers.
  • A feature that a build or the config can turn off, such as search or releases: a flag in /info. A missing field is not this signal, because a field is also missing when httpd fails to compute it. The client must not hide a feature because of such a failure.

No version but httpd's. httpd does not report apiVersion, and serves the API at /api, with no version in the path. When a path moves, the client cannot tell from a response which path a seed has. So it keeps the old path until explorer drops the last httpd release without the new one, and httpd serves the old path until the first major release after that.

Forward compatibility

Explorer does not support httpd releases that are newer than itself, and it does not need to. Explorer and httpd live in one repository, and a patch that changes the API also updates the client. radicle.network deploys explorer continuously, so it is not older than a released httpd. A self-hosted explorer should track the latest version for the same reason.