Azure APIM issues reapplying swagger file with altered operationId(s)

Question

Hi Azure community,
We've faced issue where reapplying validated swagger onto API fails with error:
One or more fields contain incorrect values:
{"code":"ValidationError","message":"One or more fields contain incorrect values:","details":[
{"code":"ValidationError","message":"Operation with the same method and URL template already exists: GET, /loss-model/{name}/{version}/incompatibility-list","target":"urlTemplate"},
{"code":"ValidationError","message":"Operation with the same method and URL template already exists: GET, /loss-model/{name}/{version}/incompatibility-list","target":"method"}]}

Actual difference in reapplied swagger file are values of particular "operationId" params in it (swapped locations):

New swagger file being applied is fully valid and is being applied just fine if operationId values are not swapped as in the example...
...however our concern is that "swapped-operationId" swagger file is still fully valid, so this seems like a bug on Azure/APIM side that it is unable to be successfully applied?

Are we missing something here or it should be considered a bug and be reported?

Thank you in advance.
Regards,
Lukasz

Answer 1

OK, seems this behavior is actually documented in:
https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions#update-an-existing-api-via-openapi-import

Update an existing API via OpenAPI import During import, the existing API operation:

• Changes to match the API described in the OpenAPI document.
• Matches to an operation in the OpenAPI document by comparing its operationId value to the existing operation's Azure resource name.
  • If a match is found, existing operation’s properties are updated "in-place".
    • If a match isn't found: - A new operation is created by combining HTTP method and path template, for example, get-foo. - For each new operation, the import will attempt to copy policies from an existing operation with the same HTTP method and path template.

All existing unmatched operations are deleted. To make import more predictable, follow these guidelines:

• Specify operationId property for every operation.
• Refrain from changing operationId after initial import.
• Never change operationId and HTTP method or path template at the same time. Update an existing API via OpenAPI import During import, the existing API operation:
  • Changes to match the API described in the OpenAPI document.
  • Matches to an operation in the OpenAPI document by comparing its operationId value to the existing operation's Azure resource name.
    • If a match is found, existing operation’s properties are updated "in-place".
      • If a match isn't found: - A new operation is created by combining HTTP method and path template, for example, get-foo. - For each new operation, the import will attempt to copy policies from an existing operation with the same HTTP method and path template.

All existing unmatched operations are deleted. To make import more predictable, follow these guidelines:

• Specify operationId property for every operation.
• Refrain from changing operationId after initial import.
• Never change operationId and HTTP method or path template at the same time. [...]

...so in other words - one needs to cross-check his updated OpenAPI doc/Swagger file against previously imported one - even though one would think new one is perfectly valid formally.

Answer 2

Hi @Łukasz Oracz,

I'm glad that you were able to resolve your issue and thank you for posting your solution so that others experiencing the same thing can easily reference this!

Since the Microsoft Q&A community has a policy that "The question author cannot accept their own answer. They can only accept answers by others", I'll repost your solution in case you'd like to "Accept" the answer.

Issue:

When attempting to reapply a modified and valid Swagger/OpenAPI file to an existing API in Azure API Management (APIM), the process failed with validation errors due to existing operations having the same HTTP method and URL template. The issue arose despite the new Swagger file being formally valid, with only operationIds swapped and no duplicates.

Solution:

The issue was resolved by aligning the operationIds in the new Swagger file with those used in the previously imported version. Although initially perceived as a bug, this behavior is actually documented in Microsoft's API import restrictions. The documentation outlines how APIM applies imports:

• During import, APIM matches operations using the operationId as the Azure resource name.
• If a match is found, it updates the operation in-place.
• If operationId is changed along with method or path, it causes conflicts or new operations to be created.
• For reliable behavior, it is recommended to:
  • Avoid changing operationId after initial import.
  • Never change both operationId and method/path at the same time.
  • Ensure operationId is specified for every operation.

So, to avoid such issues, the updated Swagger file should be carefully cross-checked against the existing one to maintain consistency in operationIds for any unchanged methods and paths.

Please click Accept Answer and kindly upvote it so that other people who face similar issues may get benefitted from it.