Tell clients the current API version so they can tell if they're out of date

[david-crespo]

Pulled out of #9425. The simplest way I can think of for this to work would be to include the current API version in a response header for all requests, and the console can figure out what to do with that. You could also imagine the CLI using this to print a warning to stderr or something.

The motivating scenario is:

1. User loads the web console, then goes and takes a nap.
2. A system update happens. The API version no longer matches what their loaded console expects. Nexus has a new copy of the console on hand but the user has not requested it yet.
3. The user wakes up and comes back and navigates somewhere in their existing console session, e.g., by clicking a link.

Console navigations happen client-side — they do not refresh the page. Assuming their session is still valid (idle timeout is 8 hours) a few things could happen here:

• The navigation could trigger the background fetch of a JS file the user does not have cached, and this file is no longer on Nexus because the console files have changed. The background fetch 404s, which I think bubbles up to a page-level Something Went Wrong. The user refreshes and gets the latest console.
  • It's possible that this fetch does not 404, because there can overlap in the list of JS chunks between releases, though this basically never happens. But if it does, we fall through to the next possibility.
• The JS loads fine and an API request goes through that has removed a field the console relies on, so the console blows up with Something Went Wrong. The user refreshes and gets the latest console.
  • This should be extremely unlikely because of the API version translation machinery — the API knows how to receive old request and how to respond with a shape the old client can handle.
  • New fields shouldn't be a problem, they will just be ignored.
• Everything works fine, they're just missing new stuff

After writing this all up, it seems to me the most likely failure case by far is actually the first one, which would not be helped by adding the API version to a response header unless the console is polling something in the background or using refetchOnWindowFocus: true (we have it off currently). That would mean that whatever "hey bud refresh the console" warning we set up would appear before the user chooses to do the nav that sets off the series of potential catastrophes outlined above.

[davepacheco]

Pulled out of #9425. The simplest way I can think of for this to work would be to include the current API version in a response header for all requests, and the console can figure out what to do with that. You could also imagine the CLI using this to print a warning to stderr or something.

That's pretty much what was proposed in RFD 531.

Console navigations happen client-side — they do not refresh the page. Assuming their session is still valid (idle timeout is 8 hours) a few things could happen here:

* The navigation could trigger the background fetch of a JS file the user does not have cached, and this file is no longer on Nexus because the console files have changed. The background fetch 404s, which I think bubbles up to a page-level `Something Went Wrong`. The user refreshes and gets the latest console.

Dang. RFD 531 misunderstood how this works and assumed that couldn't happen.

After writing this all up, it seems to me the most likely failure case by far is actually the first one, which would not be helped by adding the API version to a response header unless the console is polling something in the background or using refetchOnWindowFocus: true (we have it off currently). That would mean that whatever "hey bud refresh the console" warning we set up would appear before the user chooses to do the nav that sets off the series of potential catastrophes outlined above.

Makes sense, I think? It's possible we could put the response header on the 404, too, and it could check that.

[sudomateo]

I was updating our API documentation in https://github.com/oxidecomputer/docs/pull/838 when it occurred to me there's no way for clients to know which API version their Oxide deployment is running so that they can set the API-Version header appropriately.

Returning the API-Version header in responses is nice, but perhaps we can consider some version endpoint, or adding the API version to the /v1/system/update/status response.

{
  "target_release": {
    "time_requested": "2026-05-15T01:40:16.179211Z",
    "version": "19.4.0-0.ci+gitbae719a3bdb",
    "api_version": "VERSION"
  },
  "components_by_release_version": {
    "19.4.0-0.ci+gitbae719a3bdb": 458
  },
  "time_last_step_planned": "2026-05-15T08:43:14.460020Z",
  "suspended": false
}

[jgallagher]

"target_release": {
    "time_requested": "2026-05-15T01:40:16.179211Z",
    "version": "19.4.0-0.ci+gitbae719a3bdb",
    "api_version": "VERSION"
  },

I don't think we want to embed this in the update status endpoint, because the API version doesn't match the target release version while an upgrade is in progress - Nexus is updated last, so while the update to release N is happening, we're still serving API version from release N - 1 until the very end. A separate endpoint seems less confusing I think.

[sudomateo]

My only concerns with a separate endpoint.

• Are we overloading the word "version"?
• Does this endpoint only return the API Version or does it also return the Oxide version?
• Should it be /v1 or /v1/system?

The simplest setup could be this.

GET /v1/system/version
{ "version": "2026032500.0.0"}

[david-crespo]

Yes we are, and it's very tough!

#10250 (comment)

[ahl]

One of the things we've discussed is returning the current api version in a header on every response. This eg would let the CLI give a warning about being out of date without needing to make another call on every invocation.

[david-crespo]

It hadn't occurred to me that would let us avoid having an endpoint altogether because you could just hit, e.g., /v1/ping and look at the header. Though having an endpoint feels better to me. I think I'd want both.

[sudomateo]

In my opinion, it's not a good user experience to find the API version by hitting any API endpoint and looking at the response headers.

I think having both the response header and some API endpoint to query the API version makes sense.

Ultimately I would love to see us unify the RXX version and API version since it's not clear for users what both are meant to represent. I won't derail this thread though since there's already a discussion on the linked pull request.

[david-crespo]

I agree, unifying or at least coming up with a naming scheme for all the different kinds of versions is exactly what I was hoping to do in an RFD.

[ahl]

I would just note that the two versions have completely different and orthogonal purposes. The release name is an arbitrary marketing name that has no programmatic significance. We could name the next release ice cream sandwich, and the one after that jellybean, and that would be fine.

The API version is programmatically significant. Ideally, the only viewers and consumers of those numbers should be programs. And maybe programmers.

How do they intersect? Well people do know that they're upgrading to some particular version. But I would note that in the future, we expect most users of oxide to not really know. The operators will kick off the self service update. Developers will go on with their day uninterrupted. What seems to me like a good user experience for those developers, blithely unaware of the tectonic changes happening around them, is that the API consumers that they use tell them that they should update to more recent software. Ideally, it should be exactly the software to which they should update. (i.e. not "upgrade the CLI to jellybean.")