Workspace-scoped extraction and publishing uses wrong ARM paths for association resources

[petehauge]

Problem

When extracting or publishing workspace-scoped resources, the CLI uses the same ARM path patterns as service-scoped resources. However, the Azure API Management REST API defines different endpoints for several workspace association resources — using *Links paths instead of the classic sub-resource paths. This causes HTTP 500 errors when extracting workspace products and API tags on any SKU that supports workspaces (Premium, PremiumV2, StandardV2).

User impact: Workspace extraction fails with errors like:

Failed to list apis for product "my-ws-product": HTTP 500
Failed to list groups for product "my-ws-product": HTTP 500
Failed to extract API details for workspace "my-workspace": HTTP 500

Workspace products and API tags are silently skipped or cause extraction to fail.

Root cause

The workspace scope uses a different ARM resource shape for association resources. For example:

• Service scope: products/{id}/apis/{apiId} → returns full API resource
• Workspace scope: products/{id}/apiLinks/{linkId} → returns a link object with { properties: { apiId: "..." } }

The CLI currently uses the service-scope paths for all contexts, which are undocumented and return HTTP 500 in workspace scope.

Full workspace endpoint audit

Verified against REST API docs (api-version 2024-05-01) and tested live against a StandardV2 APIM instance.

✅ Working correctly — same ARM paths (17 items)

CLI Resource Type	ARM Path (relative to workspace)	REST API Operation Group	Live Test
NamedValue	namedValues/{0}	Workspace Named Value	✅
Tag	tags/{0}	Workspace Tag	✅
Backend	backends/{0}	Workspace Backend	✅
Logger	loggers/{0}	Workspace Logger	✅
Group	groups/{0}	Workspace Group	✅
Diagnostic	diagnostics/{0}	Workspace Diagnostic	✅
PolicyFragment	policyFragments/{0}	Workspace Policy Fragment	✅
Product	products/{0}	Workspace Product	✅
Api	apis/{0}	Workspace Api	✅
Subscription	subscriptions/{0}	Workspace Subscription	✅
GlobalSchema	schemas/{0}	Workspace Global Schema	✅
ApiOperation	apis/{0}/operations/{1}	Workspace Api Operation	✅
ApiOperationPolicy	apis/{0}/operations/{1}/policies/policy	Workspace Api Operation Policy	✅
ApiPolicy	apis/{0}/policies/policy	Workspace Api Policy	✅
ApiDiagnostic	apis/{0}/diagnostics/{1}	Workspace Api Diagnostic	✅
ApiSchema	apis/{0}/schemas/{1}	Workspace Api Schema	✅
ApiRelease	apis/{0}/releases/{1}	Workspace Api Release	✅

❌ BROKEN — wrong ARM paths, HTTP 500 (4 items)

These require code changes to use workspace-specific *Links endpoints.

CLI Resource Type	CLI uses (wrong)	Docs say (correct)	REST API Operation Group	Response Shape
ProductApi	products/{0}/apis/{1}	products/{0}/apiLinks/{1}	Workspace Product Api Link	{ properties: { apiId: "..." } }
ProductGroup	products/{0}/groups/{1}	products/{0}/groupLinks/{1}	Workspace Product Group Link	{ properties: { groupId: "..." } }
ApiTag	apis/{0}/tags/{1}	tags/{0}/apiLinks/{1}	Workspace Tag Api Link	{ properties: { apiId: "..." } }
Documentation	documentations/{0}	(not in REST API docs)	(none)	Should remove workspaceSupported: true — endpoint doesn't exist

⚠️ RISK — works today but uses undocumented path (1 item)

CLI Resource Type	CLI uses	Docs say	Notes
ProductTag	products/{0}/tags/{1}	tags/{0}/productLinks/{1}	Workspace Tag Product Link. Classic path returns 200 today but is not the documented workspace endpoint. Should migrate to productLinks to avoid future breakage.

🔲 GAP — missing workspace support (4 items)

REST API Operation Group	ARM Path	CLI Status	Notes
Workspace Api Version Set	apiVersionSets/{0}	VersionSet type exists but NOT marked workspaceSupported	Workspace version sets won't be extracted. Easy fix: add workspaceSupported: true.
Workspace Policy	policies/policy	ServicePolicy exists but NOT marked workspaceSupported	Documented in REST API. Returns 500 on StandardV2 (may be a service-side issue).
Workspace Certificate	certificates/{0}	No Certificate resource type in CLI	New resource type needed. Endpoint works on StandardV2.
Workspace Tag Operation Link	tags/{0}/operationLinks/{1}	No equivalent in CLI	Tag ↔ operation associations not extracted for workspaces.

Key implementation notes

1. Link resources have a different response shape. Instead of returning the full resource, they return a link object:

   {
     "name": "linkId123",
     "properties": { "apiId": "/subscriptions/.../apis/my-api" }
   }

   The name field is an opaque link ID, not the associated resource name. The actual resource name must be extracted from the properties.*Id field.

2. Link resources use absolute ARM resource IDs in workspace scope (not relative paths).

3. The ProductPolicy path (products/{0}/policies/policy) works correctly in workspace scope — no change needed. Only the association endpoints (apis, groups, tags) use the link pattern.

4. Service-scope endpoints are NOT affected. The classic products/{id}/apis, products/{id}/groups, and apis/{id}/tags paths remain documented and functional at service level.

Related

• Workspace-scoped override properties not applied #118 — Workspace-scoped override properties not applied
• Workspace-scoped sub-resource filtering not implemented #119 — Workspace-scoped sub-resource filtering not implemented
• Enable workspace testing on StandardV2 SKU in integration tests #126 — Enable workspace testing on StandardV2 SKU in integration tests