Search code examples
restwebapi-design

Rest endpoint for fetching data with 2 input params - should the type of fetch be explicit or determine it implicitly?

I'm building an endpoint, let's call it /explore, where data can be requested in two ways:

  1. Provide a lat,lng as required params with some optional/default params to find results within a certain distance of a location. This is useful for clients that are perhaps displaying a list view of results.

  2. Provide a bounding box NE lat,lng, SW lat,lng as required params to find results within that region. This would be useful for clients that are using a map view.

What is considered a better practice in this case?

Should the API consumer provide an explicit type=map or type=list, or should I the developer allow the consumer to pass EITHER a bounding box or latLng pair and based on the inputs determine what to send back?

Thanks

Solution

  • I would decide based on whether a single coordinate was passed or a bounding box. That prevents a class of errors where the type equals bounding-box, but only a single coordinate is passed in (or vice versa)

    The first request in the list below would return a list, where the second would return the bounding box.

    GET /explore?coord=lat,lng

GET /explore?ne=lat,lng&sw=lat,lng