Skip to content

Detect which API version an appliance serves - #5

Merged
JonahMMay merged 1 commit into
mainfrom
feature/api-discovery
Aug 14, 2026
Merged

JonahMMay merged 1 commit into
mainfrom
feature/api-discovery

Conversation

@JonahMMay

Copy link
Copy Markdown
Member

The REST API carries its version in the path — /api/v8.1/... — and nothing negotiates one for the caller, so every consumer has to pick a version up front and hard-code a guess. detect_api_version() removes the guess: it probes /api/v{version}/system/about for each version this package ships and returns the newest one the appliance routes.

That endpoint is the discriminator because it requires a bearer token, so an anonymous probe separates the two cases by status alone: 401 (or 403, or 200 where it is ungated) means the version is served, 404 means routing found nothing. No credentials needed, so it can run before any exist.

Only 8.1 ships today, which makes the answer trivial now and correct later — the candidate list is VERSION_TO_PACKAGE, so adding a version to the package is all it takes for detection to consider it.

Best-effort by contract. Unreachable appliances, proxies that rewrite statuses and anything else unexpected all return None, so a caller falls back to a version of its own choosing instead of failing. Probes run concurrently, so detection costs about one round trip.

detect_rest_api(host) additionally sweeps port x version and returns a RestApiEndpoint(port, api_version), for deployments reached through a port-forwarding proxy rather than on 443.

Also adds pytest-asyncio and a testpaths setting, which the repository needed to run its first tests.

The REST API carries its version in the path — /api/v8.1/... — and nothing negotiates
one for the caller, so every consumer has to pick a version up front and hard-code a
guess. detect_api_version() removes the guess: it probes /api/v{version}/system/about
for each version this package ships and returns the newest one the appliance routes.

That endpoint is the discriminator because it requires a bearer token, so an anonymous
probe separates the two cases by status alone: 401 (or 403, or 200 where it is
ungated) means the version is served, 404 means routing found nothing. No credentials
needed, so it can run before any exist.

Only 8.1 ships today, which makes the answer trivial now and correct later — the
candidate list is VERSION_TO_PACKAGE, so adding a version to the package is all it
takes for detection to consider it.

Best-effort by contract. Unreachable appliances, proxies that rewrite statuses and
anything else unexpected all return None, so a caller falls back to a version of its
own choosing instead of failing. Probes run concurrently, so detection costs about one
round trip.

detect_rest_api(host) additionally sweeps port x version and returns a
RestApiEndpoint(port, api_version), for deployments reached through a port-forwarding
proxy rather than on 443.

Also adds pytest-asyncio and a testpaths setting, which the repository needed to run
its first tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@JonahMMay
JonahMMay merged commit ebc01ed into main Aug 14, 2026
2 checks passed
@JonahMMay
JonahMMay deleted the feature/api-discovery branch August 14, 2026 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant