Reviewing the Plazes APIs
Plazes is an extremely cool location awareness service. Recently the first version of the Plazes API was released. Together with the Launcher and WhereAmI APIs there now are three public APIs for the service. As a hobby project I’ve updated the RubyForPlazes project, run by Peter Rukavina, to work with the new API. The new version hasn’t officially been announced yet, as there is still some work to do with regards to testing and examples, but it is already in the repository at Peter’s site. During the development of the new Ruby implementation I’ve run across a number of issues with the API design, which are documented in this article.
Please note that the properties referred to below are as used in the Ruby implementation, not necessarily the Plazes APIs.
Plaze? What Plaze?
One problem is that all three APIs return different information about a Plaze, and with different property names for equal values. The data returned by all APIs, with normalized names:
- key: Identifier for the Plaze
- name: Name of the Plaze
- city: City where the Plaze is located
- country: Country where the Plaze is located
- latitude: Latitude for the Plaze
- longitude: Longitude for the Plaze
- url: URL for the Plaze on Plazes.com
The WhereAmI API doesn’t return more information than this. Actually, it returns even less. The Plaze key is not returned, but it is part of the URL.
The Launcher API returns:
- timezone: Plaze timezone
- feed_url: URL to the RSS2 feed for this Plaze
And finally, the Plazes API:
- street: User entered address for this plaze. Includes street number or other address parts when applicable
- state: User entered US or Australian state for this plaze
- zip: User entered ZIP code for this plaze
- blog_url: User entered URL for this plaze, can be empty
I’d love to see the timezone and feed_url added to the Plazes API. feed_url by itself isn’t enough, as it returns an RSS 2.0 feed while RSS 1.0 and Atom 0.3 (which is deprecated) are available as well. The feed URIs are predictable, though, and the Ruby implementation supports this. And while it is annoying that the property names differ between APIs, it is easy to abstract this away.
Users
User information is slightly different between the three APIs as well. You could say there is a base user, which has:
- key: Identification key of the user on Plazes.com
- name: Name of this user.
This is the minimum of user information returned by the plaze.comments and plaze.photos methods of the Plazes API. The base user is an abstraction, though. The mentioned methods return the values as user_key and user_name properties on the general result.
Then there is a normal user, returned by the plaze.people method of the Plazes API and which properties are shared by the other methods described below:
- thumbnail_url: URL to a thumbnail picture of the user on plazes.com. Always set, can point to a dummy image
- url: URL to the users profile page on plazes.com
- blog_url: URL the user entered as her blog, can be empty
- message_url: URL on plazes.com where internal messages can be sent to that user
user.friends returns:
- plaze: The current plaze of the friend. Only available if the friend is online.
- distance: The distance of the friend to your current plaze. Only available if the friend is online.
Note: The actual result from the API contains a normal user, a Plaze and the distance. Since the distance and Plaze are properties of the friend I’ve implemented the result as one object.
Finally, the Launcher API has a plazes.buddies method which returns a normal user and it’s vicinity to your location.
It’d be great if the result from plaze.people is the same as the result from user.friends, especially with the distance. An online property would be handy too, currently this has to be inferred from the presence of other properties and the way the user object is requested. The plazes.buddies method could return the same information and drop the vicinity, as this can be derived from the distance. In fact, since the Launcher API requires a special API key, this is what’s done in the Ruby implementation already. Furthermore, there should be a user.info method which returns this information for a given user key.
Other data types
There are other data types available in the APIs, which have a good definition. I won’t go into detail about these types but you can find them in the Ruby implementation.
Concluding
The Plazes APIs need some clean-up, especially when it comes to plaze and user information. The API results refer to abstract structs, such as the user and plaze struct, instead of extending from them. Extending makes more sense when you are using the API.
It would be useful if the next version of the Plazes API would supersede all three existing APIs. An updated Launcher API would be welcome as well, looking at the recent Plazer apps it can be concluded that this API already exists, but is private.
Very well-written assessment. It does sound like these APIs have grown up over time, and now need to be merged and pruned. Ideally there would be a single service interface to Plazes, with methods for plaze and user with appropriate data returned for each. It wouldn’t be so bad to make such a change, as long as backward compatibility was retained - the Google and Amazon web service APIs have changed over time.
andyp | 7 May 2006, 17:34 | link