Skip to content

Fallback to older endpoint versions and warn on older Jamf Pro tenants #215

@neilmartin83

Description

@neilmartin83

Problem

jamf-cli is generated against the latest Jamf Pro OpenAPI spec. When run against a tenant on an older Pro version, two failure modes occur:

  1. Per-command 404s. The generator picks the highest available version of each endpoint and drops the lower ones. See deduplicateVersionedOps in generator/parser/parser.go:1032 — when both /v2/foo and /v3/foo exist in the spec, only /v3/foo is emitted. If the target tenant only implements /v2/foo, the command 404s with no graceful path.
  2. No global heads-up. A user on, say, Jamf Pro 10.50 running a CLI built against 11.x has no warning that broad swaths of commands may fail. They discover incompatibility one 404 at a time.

Proposal

1. Per-endpoint version fallback

For endpoints where the spec defines multiple versions of the same path/method:

  • Generator emits all versions instead of dropping the lower ones — highest version is tried first, and on 404 the runtime retries against the next-lower version.
  • On successful fallback, emit a one-line stderr warning: warning: /v3/foo returned 404; falling back to /v2/foo (tenant may be on older Jamf Pro).
  • Repeated fallbacks within the same process should dedupe the warning (per command, not per call).
  • Final 404 after all fallbacks exhausted → existing error path, unchanged.

Generator work:

  • deduplicateVersionedOps (generator/parser/parser.go:1032) needs to retain the version chain instead of discarding non-winners.
  • parser.Operation likely needs a FallbackPaths []string field (or similar) populated with descending versions.
  • resourceTemplate in generator/parser/generator.go emits a slice of paths; runtime helper in internal/client/ tries each in order on 404.

2. Global tenant-version check

On startup (after auth resolves, before subcommand RunE), probe /api/v1/jamf-pro-version once and compare against the Pro version the CLI was built against. If the tenant version is older than the spec version, emit a single stderr warning:

warning: tenant is on Jamf Pro 10.50.0; this CLI was built against 11.4.0 — some commands may not be available

Design questions to resolve:

  • Where does the build-time spec version come from? specs/_MonolithLibrary.yaml carries info.version: 1.0.0 (placeholder) — not the Pro version. Options: (a) capture it during make sync-spec from the monolith's info block and embed via ldflags, (b) require it as an arg to sync-spec, (c) read from a versioned spec file written alongside.
  • Should the check be opt-out? A flag like --no-version-check for CI noise reduction, or an env var.
  • Skip for commands that bypass auth. Same skipCommands list as auth resolution (config, completion, version, commands, diff, setup).
  • Platform gateway mode. The Pro-version endpoint is still hit through the gateway — verify behavior in that path.

Out of scope (for this issue)

  • Classic API has no equivalent versioning scheme — fallback applies to modern API only.
  • Pre-flight capability detection (HEAD/OPTIONS probing every command) — too chatty; fallback-on-404 is the lighter approach.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions