apiops: [BUG] Extractor - API specification.json file is overwritten by last API in extractor config

Release version

v4.3.0

Describe the bug

I have configured the extractor to extract both versions (apiA and apiA-v2) of a version set. The OpenAPI specs differ between these two API versions.

The first time I run the extractor, it creates a PR as expected with both unique specification files. I merged that PR and then – without changing anything in APIM – ran the extractor again.

This time, it creates a PR and overrides Artifacts/apis/apiA/specification.json file with the contents of Artifacts/apis/apiA-v2/specification.json file.

My extractor config looks like this:

apiNames:
- apiA
- apiA-v2

(apiA-v2 spec overwrites apiA spec)

As a test, I switched the order in extractor config, and I confirmed that the last API in the extractor config seems to override other API versions.

i.e. With this configuration, apiA spec overwrites apiA-v2 spec

apiNames:
- apiA-v2
- apiA

Expected behavior

The second run of extractor would not create a PR because nothing had changed. The APIs extracted would be independent.

Actual behavior

The second run results in a PR that overwrites apiA specification with apiB specification. The last listed API in extractor config “wins” and overwrites the other versions.

Reproduction Steps

Create an API versionset with 2 API versions.
Configure extractor to extract both of those APIs.
Run the extractor once, merge PR.
Run the extractor again and view (incorrect) PR.

About this issue

Original URL
State: closed
Created a year ago
Comments: 21 (11 by maintainers)

Most upvoted comments

Confirmed, running the code in that branches fixes the issue - thank you

beauholland on Dec 17, 2023

Nice, I am able to replicate in Postman - well done.

I think I can see the problem with parallel execution - the link generated by APIM to download the spec file is using the same file name “in-fa-acurity-account.json” for both v1 and v2.

When we make a request to APIM management APIs to export API spec files it results in the following (note: the same file name “in-fa-acurity-account.json”.

Request v1 { "link": "https://apimsttianspo5ghlkotsaqh.blob.core.windows.net/api-export/in-fa-acurity-account.json?sv=2017-04-17&sr=b&sig=wuJ3xC7%2FD1K...=2023-12-15T07:18:01Z&sp=r" }

Request v2 { "link": "https://apimsttianspo5ghlkotsaqh.blob.core.windows.net/api-export/in-fa-acurity-account.json?sv=2017-04-17&sr=b&sig=EYTLkeF33H5hbPlb...=2023-12-15T07:18:23Z&sp=r" }

Until APIM updates the export generated file name to include versioning info we are going to have todo this sequentially, not in parallel.

At least we found the problem 😃

beauholland on Dec 15, 2023

@beauholland - appreciate the offer to help.

We’re doing significant refactoring to handle workspaces, including long overdue unit/integration tests. These changes have helped identify bugs with publishing APIs. The bugs specifically affect revisions, but I’m guessing it may impact version sets too. And this effort will not be complete till next month at least.

We’re reluctant to put significant effort in the current code base that is being refactored. That said, we’ve recently pushed a few out-of-band releases for quick fixes and community contributions. If you’d like to take a crack at this version set issue, we’d certainly welcome the help. Happy to point you in the right direction as needed.

I would approach this by first understanding how the portal makes API calls during API versioning. Fire up your network inspector of choice (e.g this), play around with creating/modifying version sets, and watch the GET/PUT calls and payloads that get sent. Barring simple bugs in the code, I’m guessing we made incorrect assumptions about the sequence of API calls.

One tidbit while debugging the extractor/publisher - set your log level to Trace. This will log the URLs and payloads that the tools send to the APIM REST API. Useful for identifying wrong links, missing properties in the JSON payload, etc.

guythetechie on Dec 13, 2023

@hscheffert - My bad, I was thinking about revisions instead of version sets. As @waelkdouh pointed out, we have a Wiki that talks about how version sets are handled.

Understanding now that you’re talking about version sets and not revisions, you’re correct; APIM treats APIs in the same version set as distinct APIs. In your example, you’ll need to specify both apiA and apiA-v2 for both to be extracted.

Back to your original issue: I am able to reproduce it. Adding it to our backlog. Reproduction steps below:

Create apiA
Add v2 We now have two APIs, Original and v2.
Run extractor. We see the version set…

…and the APIs.

ApiA

Note the incorrect references to V2.

ApiA-V2

Rerunning the extractor creates a new PR that incorrectly sets both URLs to apiA.

guythetechie on Jul 18, 2023

As you probably know this is an open source project so we try your address existing issues when we get a chance. We will get to this at one point but at the moment we have other priorities within the project. So please be patient.

waelkdouh on Jul 5, 2023