[Maps - Creator] 2022-09-01-preview

[markweitzel]

Discussed in API Stewardship Office Hours on 8/3

1. Disallow multiple conversionIds on Dataset_Create
2. Change conversionId parameter from required to optional on Dataset_Create
3. Want to change conversionIds (array of string) to conversionId (string) in response
4. Want to change conversionId to optional in response

[subbarayudukamma]

Breaking Change Question 1 of 2

There are two issues associated with the PR linked. These are related to the Dataset service's Create and Get/List API.

1. ConversionId parameter will now be single valued and optional parameter : In the V2 doc, we said, multiple values are allowed. We didn’t see anyone using that way though. I’m running a query on the cold storage to look at last 12 months data to confirm.
2. The PR has the response where conversionId is optional and with name and type change. After the discussion with the board (Mike and Mark), we decided to revert those changes. We'll have the same conversionIds with array type. When the value is not there because the dataset was created using the udid, we'll populate the conversionIds array with a single value string "NotCreatedWithConversionId".

Question1 : Can we make the change in (1) above?

Production V2 API doc : Dataset - Create - REST API (Azure Maps Creator) | Microsoft Docs
Preview API doc : Dataset - Create - REST API (Documentation Preview) | Microsoft Docs

Comparisons :

Breaking Change Question 2 of 2

This is for the future change we are planning.
We have Stateset Create API as part of the FeatureState service. This is in GA. This API is synchronous now and returns the statesetId right away. We want to convert this into LRO which returns the statesetId at the end of the process. This is certainly a breaking change as the contract changes. Upon discussion with Mark, we think the below approach might work. Need confirmation/suggestions.

---------Current V2.0
POST https://{geography}.atlas.microsoft.com/featureStateSets?api-version=2.0&datasetId={datasetId}&description={description}

GET https://{geography}.atlas.microsoft.com/featureStateSets/{statesetId}?api-version=2.0
PUT https://{geography}.atlas.microsoft.com/featureStateSets/{statesetId}/featureStates/{featureId}?api-version=2.0

---------2023-01-01-preview, future version. Only the create API end point changes.
------- Stateset created by api-version=2.0 is NOT supported in api-version=2023-01-01-preview.
------- Stateset created by api-version=2023-01-01-preview is supported in api-version=2.0.

POST https://{geography}.atlas.microsoft.com/CachedFeatureStateSets?api-version=2023-01-01-preview&datasetId={datasetId}&description={description}
GET https://{geography}.atlas.microsoft.com/featureStateSets/{statesetId}?api-version=2023-01-01-preview
PUT https://{geography}.atlas.microsoft.com/featureStateSets/{statesetId}/featureStates/{featureId}?api-version=2023-01-01-preview

[subbarayudukamma]

Breaking change review meeting notes.

Question 1.
The scenario with worst impact is when a dataset is created with udid in V3 and List API V2 is used to see the data. The conversionId will be empty and there will be no Udid.
Since this List API is not part of the main workflow users use, we don't have any SDK and have a small customer base, we decided to take this on.
We decided to take on the other change where conversionId becomes scalar for the same reason.
Since we are previewing this new version, the idea is to let users try and give us feedback.
We need to support the V2 API for 3 years before retiring it.
We'll let our PM know of these changes and let him take the final call.

Question 2.
We decided to go with the breaking change for this one too as a preview as long as the artifacts created in V2 are supported by V3 APIs and vice versa.
Again V2 should be supported for 3 years and the artifacts of V2 should continue to work in the future versions.
The POST API URL and query parameters are NOT to change at all. Just the response would change as it becomes LRO.

Since these are separate services, they can go out at different times. Better GA them together to make it easy for the users to make all the breaking changes at once.

[mikekistler]

Jeffrey and I met with the Maps team today to discuss the breaking changes. They mentioned that their PR (#20009) is not flagged as "BreakingChangesReviewRequired" and I wanted to investigate that. Here's what I found:

• The conversionId parameter is not flagged as breaking because it was always defined as type: string and the ability to pass multiple of them was only documented in the description. So our tools would not catch this change.
• The change from conversionIds (an array) to the single conversionId in the output was detected by the breaking change tooling but only flagged as a "warning". This is wrong. I opened an issue to get this fixed.

[mikekistler]

Update: It turns out that the breaking changes tooling didn't flag second change above because the "2.0" API version appears to be a preview (it is in the "prevewi" folder), and the tool does not flag breaking changes when there is no stable version.

In this particular case, the "2.0" version seems to be misplaced, as the Maps team considers it to be "GA".