Repository navigation
agents: document GET /v2/agents/regions (ListRegions) - #1296
Conversation
Adds the per-team region catalog the console renders as its region picker. The default region is always listed; every other open region is listed only when the team holds its placement grant, so the catalog agrees slug for slug with what a create admits. Schemas are named harness_region / harness_regions_response rather than region, which already names the Droplet region schema; without the prefix the bundler renames them to definitions_region and the generated SDK types read as DefinitionsRegion. Implemented by cthulhu #183673.
| @@ -0,0 +1,4 @@ | |||
| lang: bash | |||
There was a problem hiding this comment.
Two things need addressing before this merges:
1. Path prefix conflicts with #1302
#1302 moves all Harness Runtime routes from /v2/agents to /v2/harness-runtime and calls out this PR by name: new routes should land on the new prefix. As written, /v2/agents/regions will conflict with that change. Could you move it to /v2/harness-runtime/regions, in both the paths: key in DigitalOcean-public.v2.yaml and the curl example URL? The other option is to agree on a merge order with #1302.
2. Descriptions contradict how placement works today
The operation description says every returned slug "is accepted as the region a session or config is created in". is_default is described as "the region a create lands in when none is named". But create_session_request.region on main says:
Optional placement check, not a placement choice: the session is always created in the region whose API host served the request. If set, it must equal that region, or the request fails with 400 and a region_mismatch message. Honored only for teams on the regional routing rollout; ignored otherwise.
So a client can't choose a region by passing a slug. Placement comes from the regional API host it calls. Could the operation description, harness_region.slug and harness_region.is_default explain how a caller actually uses a returned slug, for example which host to target? It would also help to say how this behaves for teams that aren't on the regional routing rollout.
There was a problem hiding this comment.
Both points are correct. Done in 0d7cd80.
1. Prefix. The path and the curl example are now /v2/harness-runtime/regions. This removes the conflict with #1302, thus no merge order is necessary.
2. Descriptions. You are right that they contradicted create_session_request.region. A caller does not choose a region with a slug. The host decides the placement. The text now says this:
slugnames the regional API host to call.ric1ishttps://api-ric1.digitalocean.com.is_defaultnames the region that the region-less host,https://api.digitalocean.com, serves.- The operation says that the optional
regionfield on a create is a check against the host, not a choice. It also says that a team outside the regional routing rollout sees only the default region, and gets noregionfield on its responses.
The same text is corrected in godo digitalocean/godo#1209, thus the SDK and the spec agree. That change is a follow-up to digitalocean/godo#1199, because it came after that PR merged.
make lint gives 0 errors.
…g is used Moves the path and the curl example to /v2/harness-runtime/regions. #1302 moves the documented Harness Runtime surface to that prefix and names this PR; a new route under /v2/agents would conflict with it. Rewrites the descriptions. They said a returned slug "is accepted as the region a session or config is created in", which reads as a placement choice. create_session_request.region says the opposite: the session is always created in the region whose API host served the request, and the body field is only a check against that host. The slug now names the host to call, is_default names the region the region-less host serves, and the operation says what a team outside the regional routing rollout sees. Reported in review by @DO-rrao.
Summary
Documents
GET /v2/agents/regions, the per-team region catalog the console renders as its region picker. The default region is always listed and is markedis_default; every other open region is listed only when the team holds its placement grant, so the catalog agrees slug for slug with what a create admits — a picker built from it never offers a region a create refuses.Draft: do not merge yet
This spec describes the production API, and this endpoint is not in production yet. It is implemented by an open internal PR (cthulhu #183673) and is still refused at the edge until the matching extauth change lands. Opened early so the client-generation checks run and the UI work has the contract to build against.
Ready to merge once the implementation is merged and deployed.
Changes
resources/agents/agents_list_regions.ymlharness_list_regionsresources/agents/models/definitions.ymlharness_region,harness_regions_responseresources/agents/examples/curl/agents_list_regions.ymlDigitalOcean-public.v2.yamlModeled on
agents_list_session_sandbox_sizes— the nearest sibling, a read-only catalog that feeds a picker — down to the response set, the rate-limit headers and theHarness Runtimetag.Naming
The schemas are
harness_region/harness_regions_responserather thanregion, which already names the Droplet region schema. Without the prefix the bundler renames them todefinitions_regionand the generated SDK types read asDefinitionsRegion; the prefix also keeps the Go SDK clear of its existingRegion.Verification
make lintpasses with 0 errors. The 8 warnings are all pre-existing onmainand none are in the files this PR adds or changes. The bundled spec resolves the200to#/components/schemas/harness_regions_response, and the collision-renamed schema list is unchanged frommain.Not run:
make test(needs the Docker mock proxies), and no live request — the endpoint is not deployed.