{
  "id": 30490,
  "title": "The one design-review question that would have caught our APIM naming collision",
  "url": "https://urgent.news/2026/08/02/the-one-design-review-question-that-would-have-caught-our-apim-naming",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-08-02T04:49:12.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/webruster/the-one-design-review-question-that-would-have-caught-our-apim-naming-collision-4eho"
  },
  "original_language": "en",
  "account": "On a seemingly routine day at Azure API Management, a PUT request was met with a puzzling error: \"Property with the same name already exist.\" The incident occurred when a pipeline attempted to update a named value, but was rejected by the platform. Initial suspicion fell on a recent script change, but upon investigation, it was discovered that the root cause lay in a design oversight. Azure API Management's named values carry two identifiers - one derived systemically (id) and another designated for display (name). While the system ensures uniqueness for the name field, it does not enforce this for the id field. This discrepancy often goes unnoticed in design reviews because most engineers assume the ID is universally unique, missing the critical distinction between the two. In the case at hand, a named value with the same name existed prior to the pipeline's attempt, but under a different id. This subtle design flaw allowed the API Management system to reject the update without indicating the underlying issue. The incident is not unique to Azure; similar problems have been observed in other platforms and technologies worldwide, highlighting a broader design gap. The fundamental question that would have prevented this error is whether a resource has multiple identifiers, which one is unique, and at what scope. This question is frequently overlooked in design documentation, leading to unnoticed collisions in production environments. To mitigate such issues, the author suggests adding a specific line in design doc templates: \"For every resource with a compound identity, explicitly state which field is unique, at what scope, and the collision handling procedure.\" This simple addition would force designers to verify and document the compound identity, thus preventing future \"silent overwrites\" and cryptic error messages.",
  "summary": "The article discusses a design-review oversight that led to a naming collision issue in Azure API Management (APIM). The error occurred when a PUT request failed due to a named value with the same name already existing in the system, despite the API's attempt to create a new one. The root cause was that APIM uses two separate identifiers for named values: an ID derived from the artifact folder name and a name field that must be unique across the entire service. The design document did not explicitly state which field was unique, leading to the collision. The author emphasizes the importance of asking the right design-review question: whether the resource has multiple identifiers, which one is unique, and the scope of uniqueness. Implementing a simple addition to the design doc template to address this issue could have prevented the incident.",
  "key_points": [
    "Azure API Management named values have two identifiers: systemically derived ID and display name.",
    "Design review often overlooks the distinction between ID and name fields for uniqueness.",
    "Adding a design doc template line could prevent \"silent overwrites\" and cryptic errors."
  ],
  "editors_take": null,
  "illustration": "https://urgent.news/ill/30490.png",
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}