Azure / Azure/api-management-developer-portal

Content import: 412 "permalink must be unique" enforced only on Premium multi-region instance is inconsistent across tiers

Open
#2,899 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.