Returning a source by location and geolocation

[Jet Basrawi]

Hi,

We currently have an API that looks like 

GET /dealer-information/dealer/{dealerid}

GET /dealer-information/dealers

GET /dealer-information/availableServices

GET /dealer-information/getDealersByGeoLocation

GET /dealer-information/getDealersByLocationName

...

etc and all pretty crappy

I would like to refactor to be 

GET /dealers

GET /dealers/{dealerid}

GET /dealers/{dealerid}/services

etc

I am not sure how to proceed with the location ones though. My first thought would be

/dealers?long=123464454&lat=34553534534 to replace /dealer-information/getDealersByGeoLocation

/dealers?location=London to replace /dealer-information/getDealersByLocationName

What do we think? Is this the right way or is there a better way?

Bear in mind I am trying to implement a pragmatic version of REST as promoted by the Apigee guys so developer understanding and simplicity takes precedence in my design goals.

[Oliver Wolf]

I am not sure how to proceed with the location ones though. My first thought would be

/dealers?long=123464454&lat=34553534534 to replace /dealer-information/getDealersByGeoLocation

/dealers?location=London to replace /dealer-information/getDealersByLocationName

What do we think? Is this the right way or is there a better way?

I think this quite ok and pretty much what I frequently see in other APIs. Essentially, you’re GETting a representation of the current state of a collection of dealers, filtered by location – nothing wrong with that.

Be careful though with excessive precision in the geolocation parameters. They’re part of the URL and thus of the key used to cache the response, so in your case I’d expect lots of cache misses. Is the list of dealers for location long=123464454&lat=34553534534 really different from the one for location long=123464453&lat=34553534535? Probably not, so you might want to define reasonable clusters and redirect to the URL identifiying the cluster, like this:

Req:

GET /dealers?long=123464454&lat=34553534534

Resp:

HTTP/1.1 303 See Other

Location: http://your.api/dealers?location=London

Oliver

[Vijay Aravamudhan]

I agree with Oliver's POV. The REST-style of thinking about the 'get by location name' and 'get by geolocation' seem aligned with filtering based on certain parameters. This is how I implement my index (GET) calls that return collections.

One caveat is to ensure that you don't go overboard and expose too many such "filter criteria". Another security-related issue is to not expose your ultimate datastore (database?) table/column names as the query parameters.

In case you end up supporting multiple such filters, it would also help consumers if you can specify (either via documentation or some other way), whether the logic being done to combine these criteria is going to be an AND or an OR. (If there's a way that the consumer can specify this, it would be even better, but I haven't come across an easy/clean way to do this yet).

Thanks,
Vijay

Vijay Raghavan AravamudhanLead Code Agitator/Polisher

Email

vrar...@thoughtworks.com

Telephone

+91 87544 90705

Personal blog: http://vijaysspot.blogspot.com/

Technology and business move fast, so ThoughtWorks releases a new edition of Technology Radar every six months. Today the newest edition published. Get your copy here: http://thght.works/1yWtblX

ThoughtWorks is a transnational IT professional services firm serving our clients from offices in Australia, Canada, China, Brazil, India, Germany, Singapore, South Africa, the United Kingdom and the United States.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.