Upcoming Amara API Changes

The Amara API is going to be going through some exciting changes in the near future.  I’d like to take this opportunity to explain the reasons behind the change and discuss what it means for people who interact with the Amara API.

First off, let me say that there are no plans to change how the API endpoints themselves work in the short term.  All of the current endpoints will stay around and there are no plans to change the interfaces.  We are planning a small change to the URLs, but  that’s it and there will be a transition period when both the old and new URLs work.

So what is changing?

First off, we’re going to be doing a refactor of the code for several reasons:

• We want to clean up the API code that we’ve written, which could definitely use it.
• We want to switch from an old version of tastypie to django-rest-framework.  This has the nice benefit of providing browser-friendly endpoints.  They’re pretty awesome for exploring and debugging the API.
• We want to move most of the API to our public repository

Like I said, this will only be a refactor.  All current functionality should still stay the same.  That said, it’s going to be a somewhat large code change.  If you have client code that interacts with our API, I would definitely recommend testing it with our new code during the transitional period.

The other thing that’s going to happen is a switch to how we handle changes to the API.  Right now we use a versioning system, where the version is included in the API URL (the /api2/ prefix).

This system isn’t really working well.  First off there are semantic issues with including the version in the URL.  But the main issue is it doesn’t fit in with the way we work on amara which is based on agile, iterative development.  It’s much better for us to make small, incremental changes, then to try to save them all up and then make a huge API change with a new version.  In fact, we have made several small changes like this to the API in the last few months and kept the API version the same.

What we’d like to switch to is a system where the API URLs don’t include a version.  Instead of http://amara.org/api2/partners/videos/ we will use something like http://amara.org/api/videos/.  Under the new system, it should be expected that small changes will happen over time.  To make changes as least painful as possible, we will provide tools to help API client manage them:

• We have created the Amara API Changes email list to communicate API changes.  Whenever we are planning to make one, we will announce it on our blog, announce the date when it will happen, and send an out an email to the list.
• Before the switchover date, we will return an HTTP header to indicate that the API will be changing.  The name will be X-API-DEPRECATED and the value will be the switchover date in YYYYMMDD format.
• Clients can start using the new API before the switchover date using the X-API-FUTURE header.  The value should be the date of the API that you want to use, also in YYYYMMDD format.  If the X-API-FUTURE date is >= the switchover date then the new API code will be used.  If this date is in the past it will be ignored.

When will this all happen?  This isn’t set in stone right now, but I think this will be the rough schedule:

• 2-4 weeks to implement the new API endpoints using the new URLs:  At this point users can try testing their clients against the new API code.  We will send an email and post to our blog as we implement endpoints.
• 2 week early transition period:  At this point the new URLs will all be implemented and you are encourage to switch your client code over to using them.  The old URLs will continue to work as usual
• New world order: after the transition period the old URLs will redirect to the new ones.