[Azure Maps - Azure Maps] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: Azure Maps - Azure Maps
Review Created By: Will Huang
Review Date: 05/02/2024 08:00 AM PT
Release Plan: API only
PR:#28940
Hero Scenarios Link: Here
Core Concepts Doc Link: Here

Description: Azure Maps will introduce a new public preview API for the routing category: SnapToRoads and RouteRange.

Detailed meeting information and documents provided can be accessed here
For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[mikekistler]

Notes from API Review 5/2/24

• Adding SnapToRoads and SnapToRoads:batch
  • Accepts a FeatureCollection (array) and returns a FeatureCollection
  • What is inputIndex? Is it just an array index?
    • This just makes it complex -- can you get rid of it?
    • Could be useful if it was a label.
    • A single input feature results in a single snapped output feature
      • Except if the "interpolate" option is used. Complex!
• SnapToRoads should be a post-action, /route:snapToRoads
  • But that would be inconsistent with the existing patterns in this service
• This is a pageable POST! How does that work?
  • Probably should not do this
  • If you want to keep it, you need to clearly define how this works
• Do you need two endpoints? Just make the first case accept an array of 1 element
  • Single request is synchronous
  • Batch request is asynchronous -- is it?
• You can't change batch request to async later (on the same endpoint) ... should do that right away or not do it at all

Please consider these comments and schedule a follow up meeting when you are ready for re-review.

[koyasu221b]

Hi @mikekistler

• What's inputIndex :

  • For the snapToRoads method, we have the interpolate parameter, which inserts additional points between the snapped points to complete the full route path. We have an inputIndex to remap, which is the original point to be snapped.

• SnapToRoads should be a post-action:

  • To maintain consistency with the style of the Azure Maps API, we consider using this style as in V1. This alignment with the existing Bing Maps API also facilitates easier migration for users.

• This is a pageable POST! How does that work?

  • We will completely remove the pageable feature, as our load testing and the limit on snapped points (maximum of 100) indicate that it is unnecessary.

• Do you need two endpoints? Just make the first case accept an array of 1 element

  • Single is in pure GeoJSON format, which I think is more user-friendly for customers transitioning to our service. Based on BingMaps data, single requests account for a higher percentage of usage.
  • Batch can help reduce the number of client connections; you can use a single batch request to obtain multiple results. For example, browsers limit the number of HTTP connections to the same domain name. Our internal customer, PBI, needs this feature.
  • Therefore, we provide different options for various cases, similar to other providers like Google and TomTom, who offer a pure single API. I don't think it would provide a good user experience if we only offered batch processing.

• You can't change batch request to async later

  • If we have an async API, then the endpoint should be snapToRoads:asyncBatch, which aligns with the current naming convention of the Route Direction async batch API.

[mikekistler]

Notes from continuation of API review, 5/14/24

• Are your service conventions documented somewhere?
• What happens if a large batch can't be completed within the timeout (30 seconds)
  • timeouts are not user-friendly
• isDetailedShape - boolean has default of true
  • better to make boolean properties be false b
  • maybe - isSimplifiedShape
• POST in operation Id -- Maps convention
• Only reuse structures if their semantic meaning is the same -- to avoid having to separate them later which would be a breaking change.

This looks good for preview.