[Maps - Styling] REST API Review for Azure Maps Styling Service

[czubair]

Service Name: Azure Maps Styling Service

Key contact for the review: Xubin Zhuge(@xubin Zhuge) / James Jonghan Park(@james Jonghan Park)

The changes contain both existing APIs(Tileset) and new APIs(StyleRecipe, StyleSet)

The service is deployed, but the proposed changes are still in progress.

What changed in this PR:

• We create a new 2022-01-01-preview version API for Tileset, StyleSet and StyleRecipe under Creator
• We extended our exising Tileset API with Tileset Recipe ingested, and we also added Tileset Recipe GET and Validation API.
• We added two new set of APIs StyleSet and StyleRecipe which are our new APIs

Custom Styling Design doc: 

https://microsoft.sharepoint.com/:w:/t/MicrosoftMapsGeospatialTeam/EUyAGqR7R4pJoIXkXQdlQcAB7SPLJQImjNS0eQGp8xathQ?e=eccr4D

[czubair]

Review scheduled for Tues 1/25 at 1pm PST

[markweitzel]

API Stewardship Review Board 25-Jan-22

Discussion / Notes

• Conversation around ontology. When will we expect more/others. New ontology values will result in a new API version.
  • Define the ontology values as an extensible enum. This way, when SDKs are generated, they will be generate the proper language types.
  • Is there a customer benefit of deprecating the old ontology?
  • It is a breaking change if a customer cannot make an ontology with an old version. It is STRONGLY recommended to avoid breaking change. This would mean that facility-2.0 should be supported in perpetuity.
• There should be a discussion around if we should use an approved standard for the query/expression language.
• The datasetId in the POST and the body is confusing. We may need to live with this b/c of historical reasons.
  • What is the behavior if the two values are different?
• There can only be one version w/in a service sdk.
• There should be some documentation cleanup for the V2 section.
• POST should be idempotent--using the repeatability header.
• POST should return a 202
• Please reference the Handling Errors section of the guidelines to determine the proper error structure and style for errors, e.g. 400 BadRequest should be a more meaningful errors.

References

Meeting Chat
Meeting Recording

[zhugexubin]

As we discussed in the review meeting that whether we would like to introduce big broken changes to modify existing GA API behavior. The answer is no at this point. We would like to keep existing API behavior which means the new Swagger doc introduced will be consistent with the existing design pattern.