Gowalla Tools

Gowalla has rightly gained worldwide acclaim for being a first class geo-location game with some fantastic artwork and a unique approach to creating memorable locations and trips. Even before the announcement of a full API, developers had been jumping at the chance to use some of the data to create unique and useful tools and many had been able to do so thanks to the JSON files that powered a large amount of the gowalla.com website.

Once the API was launched on February 9th, there was a large amount of excitement at the prospect of being able to access more data and make even better mashups, and in turn, create a greater community for Gowalla. This has happened to a degree with developers creating everything from language specific wrappers to iPhone applications but there are serious problems with the API that are not only preventing development but also beginning to spoil the original Gowalla vision.

The major problem with the API is its fluid and changeable nature. Whilst we accept that any application will inevitably have bug fixes and changes, an API is supposed to provide a stable endpoint on which third party services can rely on. This is not the case with the Gowalla API which seems to change on a whim fairly frequently. Worse than a changing API, the developers of any applications relying on the API are rarely informed of changes (and when they are, they usually appear a day or so after the event has happened and the community have worked out fixes for themselves). This most recently happened a few days ago when the entire paging structure was changed from an offset methodology to a more standard pagination system - whilst this is a very welcome change, it meant that every application using the old method suddenly stopped working (in the best cases returning just the first page but in worst cases causing instability and crashes). The changes were reflected immediately on the gowalla.com website (which makes use of the API) but were not passed on to developers until a day later.

There are also problems with variables changing (e.g. the spots method went from returning 20 spots by default to 40, then back to 20, and now to 50 - difficult to account for when using an offset parameter), requirements for basic authentication changing (some methods require it whereas others don’t - some have started to break if you authenticate such as /items?context=vault when previously authentication was a requirement), and returned variables being removed seemingly without reason (e.g. the /trips method used to have a “published” variable to let you know if a trip had been published or not - you can still view unpublished trips but now there is no way of telling what status it has). These ever changing variables mean that any API developer has to be on constant alert for their users to start emailing and tweeting that items are broken due to the Gowalla API. Of course, the users don’t know that it is the API that is broken and assume the app creator is at fault and so negative reviews and blog posts are beginning to become common place. This is especially troubling for those developers that have created wrappers in various languages for the API as they are then under pressure from other developers using their classes who then have to implement the changes leading to days of downtime for very minor changes.

This can obviously not go on. A community can not be built upon a shaky foundation such as this and many developers are starting to stop using the Gowalla API for future projects.

The solution is relatively simple. We accept that changes have to happen but these just need to be conveyed to developers in a better way. We propose that any changes be submitted to the Gowalla Developer Group at least 1 week in advance of a change so that we can update our code as necessary. We also suggest that a “version” parameter be added across the API so that legacy scripts can continue to work without changes. In this way, a developer can move to the next API version to take advantage of any new features and data but won’t risk having their hard work undone by what could be a very minor change (e.g. renaming a parameter). It may also be worth setting up a dedicated Twitter account for API changes as Foursquare has done with @foursquareapi - this would allow you to make quick posts to the community about any changes or downtime.

Whilst the undocumented and unnotified changes to the API are by far the most important problem at present, it is worth noting that the lack of serious user authentication and write methods are also starting to cause problems. Privacy protections should of course play a large part in the future development of Gowalla but these fall hand in hand with a more solid user authentication system such as OAuth (as has been mentioned on the Gowalla Blog and Google Group several times) which would allow us, as developers, to ask for a user’s login details without worrying about the security implications which are currently present. There are several applications out there already taking down user’s full login information as certain methods within the API require login information to access them. A large number of these work by authenticating with any account (not necessarily the account you are asking for information about) and therefore need to be refactored to either not require authentication or to instead use OAuth. This ties in with adding write methods to the API to allow developers to add the ability to check-in, add friends, swap items, and create trips. We understand why this ability is publicly lacking at the moment to prevent cheating the system, but currently cheating is already becoming a large problem. This is partly due to basic authentication methods that are hidden in the API which can (and have been) exploited and also due to the mobile web version of Gowalla which makes it trivial for anybody with any basic Javascript knowledge to check themselves in anywhere in the world.

With regards to cheating, it should be fairly simple to ascertain if somebody is checking-in illegally as you can measure the time and distance between two spots and see if the speed is over a certain threshold (e.g. if you have checked-in at Austin and London within 2 minutes then there is obviously a problem). An automated system could monitor such things and then suspend an account giving it limited permissions (e.g. no item trading) until a Gowalla developer (or STE member) has a chance to review the account and unlock or ban the user.

One option for write access might be to enable it for API users on a case by case basis e.g. you could review any application that wants write access and ensure that it has appropriate safeguards to ensure that a user is at a spot before they can check-in or that it isn’t going to allow people to create thousands of spots around the world without actually going there. Whilst this would create an overhead for you I’m sure there are volunteers within the community that would be happy to perform this role for you.

There are a few other minor suggestions that we feel would help boost the Gowalla API Developer community and bring it more in line with other similar services:

• Creating a directory of applications that use the API (such as Foursquare has)
• Updating the documentation to be more relevant - most of the requests on the Google Group Developer boards are asking for clarity on methods that exist or asking why certain methods are unavailable. Linking to wrapper libraries created by the community would also be a good idea. Take a look at the Foursquare API and Twitter API for great examples of good API documentation.
• Becoming more involved with the community by posting regular updates about what you’re doing, what you’d like to see, and any changes that are upcoming. At the moment, the only communication seems to come after something major has broken and people are complaining - we’d like to see the Gowalla Developers sharing their knowledge and expertise of the system to help us all make something great (e.g. Scott Raymond, Alamofire Developer, made a fantastic program to show Growl notifications for Gowalla Check-ins with Growalla - It would be great to have stuff like this shared within the developer boards and in an app directory to inspire people to make these kinds of applications)

As we’ve mentioned all of these issues are important but by far the most pressing issue at the moment is that of communicating API changes to the development community and in limiting the number of changes that are occurring. Without a definitive solution to this problem, the Gowalla API will end up being mistrusted and therefore unused by the very developers who are trying to promote Gowalla worldwide.

Signed,

The following signatures are from developers around the world who have built applications using the Gowalla API - they form the majority of API developers who have contributed on the Gowalla Developer Group. They have agreed to show their support for changes to the API by signing below.

If you would like to add your support to this letter, just send a tweet to @gowallatools and we'll add your Twitter username below.

@cassandrarife, @maique, @Wildheart_Baby, @stuartreeve, @achimh, @geeners, @LukeJesse, @lonelycoo, @PinkBatgirl, @ericl, @elucidation_inc, @ikbenmartijn, @The_BORG, @sobileme, @Bgniko, @ancyru, @location_x, @bkw27, @pandapoo, @faiththiang, @tonyinNYC, @hortonk, @neyo, @lee_nixon, @johngarcia, @jallin, @megmacs, @willimac, gurucube, @yvesremedios, @TweetAngi

Josh Williams, Gowalla CEO - Speaking to TechCrunch

"As a small team we have been diligently focused on improving performance and positioning Gowalla for the future. We recognize this may have affected some of our developers over the past few weeks and we are actively working to strengthen communication and create an even more robust experience for our entire community."

Scott Raymond, Gowalla CTO - Commenting on the Gowalla Developers Google Group

I'm sorry that our communication about API issues hasn't been better in the last couple of weeks. As Rob mentioned in the original post, in recent days we shipped a pretty major in-flight re-engineering of the Gowalla backend (re-writing the view and controller layers from Merb to Rails.) I'm very proud of our guys, who've been putting in long hours on the project (namely @critzjm, @andrewdupont, @robmack, and @therealadam) -- they've managed to make sweeping changes with extremely minimal downtime. As careful as we've tried to be, there have been some regressions, like stricter Accept header parsing, etc.

(Aside: it's important to note the difference between our internal API (resources and query params discovered by reading the JavaScript source, etc) and the public API (the resources enumerated at gowalla.com/api). I know there's been some breakage on both fronts, but the undocumented stuff has always been use-at-your-own-risk.)

Bottom line, I'm sorry we haven't been more responsive recently, and I'll make sure that we do a better job with that in the future. The Gowalla API is something very close to my heart. It's always going to be getting richer and deeper. In fact, one of the major motivations for the recent upgrades is to enable OAuth 2, which will enable 3rd party apps to do a lot more, and be more secure. There are a lot of cool improvements in the works, and I'm eager to get them out to the devs here.