The one design-review question that would have caught our APIM naming collision

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.