Azure / Azure/api-management-developer-portal
Content import: 412 "permalink must be unique" enforced only on Premium multi-region instance is inconsistent across tiers
- Dominant language
- TypeScript
- Stars
- 545
- Forks
- 360
- PR merge metrics
- No merged PRs in 30d
Description
Bug description
Importing developer portal content via the scripts.v3/generate tooling fails with 412 PreconditionFailed — "Value of the following properties: permalink must be unique" on a Premium multi-region APIM instance, while the same snapshot (containing two url content items with different ids and the same permalink) is imported successfully on six Developer single-region instances. All instances report platformVersion: stv2.1, identical contentTypes/url schemas (no uniqueness constraint declared, permalink only indexed: true), same api-version (2021-08-01); one accepting instance runs in the same region as the rejecting one. Timing excluded: two new url items with the same permalink created 45 seconds apart on a Developer instance are both accepted. Server-side permalink uniqueness validation appears to be enforced only by the Premium/multi-region backend — undocumented, and inconsistent with both the other tiers and the admin UI (which allows saving duplicate URL items; see #2668 for the analogous gap fixed for pages).
Reproduction steps
1. PUT /contentTypes/url/contentItems/{id1}?api-version=2021-08-01 with body {"properties":{"title":"t","permalink":"https://example.com/x"}}
2. PUT /contentTypes/url/contentItems/{id2} (different id, same permalink)
3. On Developer single-region instances both calls succeed (duplicate stored); on the Premium multi-region instance step 2 returns the 412 above — same result during bulk import via scripts.v3/generate.
Expected behavior
Permalink uniqueness validation behaves consistently across tiers/topologies — either duplicates are rejected everywhere (and the admin UI prevents saving them), or accepted everywhere. Either way, the behavior should be documented.
Is self-hosted portal?
No
Release tag or commit SHA (if using self-hosted version)
N/A — managed portal; content deployed with scripts.v3 at commit e5f21328f8939a8b2bdfac1a6cd93b8d1006c982
API Management service name
[redacted] — Premium, stv2.1, multi-region (primary East US + additional West Europe); accepting instances: Developer, stv2.1, single-region
Environment
- Operating system: Windows (Azure DevOps hosted agent + local reproduction)
- Browser: N/A (REST/tooling)
- Version: api-version 2021-08-01, azure-cli 2.88.0
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the scripts.v3/generate entry point and reproduce the two PUT requests against Developer single-region and Premium multi-region instances using api-version 2021-08-01. Compare the documented behavior with issue #2668; done means permalink handling is consistent across tiers or the behavior is explicitly documented, including the admin UI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, typescript
- Domain
- api, backend, cloud
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100