2009-06-15: API Changelog

[Sascha Konietzke]

Beginning with today we will document all changes to our API in this
group. If you want to stay up to date subscribe to the RSS Feed or to
the email notifications. We would also be happy to get feedback on the
releases. Please let us know if a feature doesn't work as expected.

We tried to finalize the API as much as possible in this release, so
there are many changes. There shouldn't be that many major changes in
future updates.

== Changes:

1. Slightly different format for errors returned in JSON format, made
it the same as for the XML format (<errors><error>message</error></
errors>).

2. Removed the "tags" sub resources for Favorites, Placemarks and
Filters as there was no real need for it and it made things more
complicated. Just read and write the tags from the comma-separated
tag_list attribute now.

3. All resources are now created under /{username}/{resource_type}.
This was partly the case before and for consistency and ease of use we
switched to this style for all Resources.

Example: Create a Link for the Placemark "golden-gate-bridge" of user
"sascha"
Previously - Post to /sascha/placemarks/golden-gate-bridge/links
Now - Post to /sascha/links and set the placemark attribute to the URL
of the Placemark: http://www.tagcrumbs.com/sascha/placemarks/golden-gate-bridge.

You can still get all the links of a Placemark at /sascha/placemarks/
golden-gate-bridge/links. But the action is read-only, if you want to
create a new Resource, use /{username}/{resource_type}.

4a. Renamed /{username}/tagcrumbs/nearby to /{username}/tagcrumbs/
suggestions. Nearby was ambiguous with /nearby. As the purpose is to
serve suggestions for the user it was renamed to suggestions.

4b. Renamed the nested elements in popular_tags from "tag" to
"popular_tag" and in recommended_tags from "tag" to "recommended_tag".
This was inconsistent behavior compared to all other actions.

5. Cleaner XML. Empty tags are now closed immediately (<tag/> instead
of <tag></tag>).

6. Removed translation attributes from City/State/Country. The name
attribute contains the translated name now in the locale that the user
specified in the settings or the locale that you pass with the query
if no user is logged in. This makes the request smaller, most of the
times you only need one language. If you need more information query
the geonames web service with the related geonameid.

7. The location of a user can now be updated and read from /{username}/
location and no longer from /location. This is more consistent. The
location of a user that is not logged in is tracked in a cookie on the
client side. You should do the same in your service. As it belongs to
a user now there is no more link to /location in /index.(xml|json).

8. Disabled HTTP Basic Authentication. Use OAuth instead. To make it
easier to get an access token we provide an HTTP Basic to OAuth
Gateway. If you want to use it drop us a line at te...@tagcrumbs.com.


That's it!

Cheers,
Sascha