As many people have noted, the Yahoo! Internet Location Platform has been released. After looking at the examples it all made sense, but two things stood out:
- Request: The use of a custom query mechanism rather than using HTTP query strings. (This is addressed in Part 1 of this post.)
- Response: The lack of URIs to identify related resources.
What follows is just a quick exploration of the second of these two issues.
URIs for Related Resources
The response documents provided by the Yahoo! Internet Location Platform do not contain any URI’s to identify related resources. This seems like a lost opportunity to make client applications less fragile and make life easier for developers. It could also make scaling on the server-side easier. (Yes, I’m talking about using REST.)
The current approach provides some of the information required to construct URIs, but the client application needs to be aware of the URI pattern to used to construct the URI for each type of resource.
There can be three types of related resources implied in a location search result:
- Related locations. e.g. Country, state, admin, locality, etc.
- Pages of matching records from the same collection of search results.
- Neighbouring geographies.
1. Related Locations:
Using the Sydney Opera House landmark search example, the related country is returned as:
<country type="Country" code="AU">Australia</country>
If an application wishes to take any action that requires knowing the centroid or bounding box of Australia it must know how to construct the correct URI to query the server. e.g.
http://where.yahooapis.com/v1/places.q('Australia')
This creates a fragile client application. If the URI construction rules, the host domain, or the URI path change then the client applications will break. The client application needs to know too much about the internal workings of the service. i.e. It is more tightly coupled that it needs to be.
An alternative solution is to identify each related resource with a fully formed URI, in the original response document, which the client application could then dereference:
<country yahoo:uri="http://where.yahooapis.com/v1/place/23424748"
type="Country" code="AU">Australia</country>
Yahoo! can then make all the changes they want to the URI that identifies the Australia resource representation without breaking client applications. It doesn’t matter if they change the URI to:
http://where07.yahoo.com/location/australia
The client application will still work provided it still understands the structure of the response document. (Data coupling is a topic for another day.)
2. Paging:
Using the Springfield place search example, when a place search matches more records than it returns in the firts response document this is indicated using:
<places ... yahoo:start="0" yahoo:count="5" yahoo:total="61">
These three attributes provide useful information for the client application, but again, in order to get the next five matching results the client needs to know how to construct the appropriate URI:
http://where.yahooapis.com/v1/places.q('springfield');start=5;count=5
It would be helpful to developers if the original response included a URI for both the next five and the previous set of records (if applicable):
<next count="5"
yahoo:uri="http://where.yahooapis.com/v1/places.q('springfield');start=10;count=5"/>
<previous count="5"
yahoo:uri="http://where.yahooapis.com/v1/places.q('springfield');start=0;count=5"/>
This is a less compelling example, because it assumes that the client application always wishes to obtain matching results in fixed size sets, whereas the approach taken by the Yahoo! Internet Location Platform allows the client application to make that choice on-the-fly.
3. Neighbouring Geographies:
The current response documents do not include any details about neighbouring geographies, but there is a neighbouring geographies query. Client applications must know how to construct yet another URI to obtain this information:
http://where.yahooapis.com/v1/place/12795711/neighbors
Why not simply add a new element to the response document that provides that URI?
<neighbors type="State"
yahoo:uri="http://where.yahooapis.com/v1/place/12795711/neighbors"/>
Conclusion:
Taking a more standardised approach to adding query parameters to URIs, and providing URI’s to related resources, would enable developers to create less fragile client applications. The Yahoo! Internet Location Platform also appears to have missed an opportunity to deliver a true REST interface in an application where it would be very well suited, however…
Caveat: All the above has been written knowing nothing about the business or design constraints that shaped the Yahoo! Internet Location Platform. There are likely to be many perfectly sensible reasons for the design choices that were made.
