One design-doc question that prevents Azure APIM naming collisions in CI/CD pipelines

A CI/CD pipeline failure in Azure API Management (APIM) was traced to a naming collision between a manually created named value and one deployed via an automated publisher, both sharing the same display name but different system IDs. APIM enforces uniqueness on the human-facing 'name' field rather than the system-assigned 'id', a distinction that is rarely documented during design reviews. The incident went undetected for months because the conflicting resource had been created through the portal by a different team member, with no platform-level warning issued to either party. The author argues that design documents should explicitly state which identifier field is unique, at what scope, and what happens on collision — a one- or two-sentence addition that forces authors to verify enforcement rules before shipping. Restricting manual portal access was considered but rejected as the wrong fix; the real gap is undocumented compound identity, not the creation method itself.