Last week, the ProgrammableWeb SEO team noticed an unusual spike in the number of page views for the Trakt.tv API profile page on the ProgrammableWeb website. After doing a little digging, ProgrammableWeb discovered that a brand new version of the Trakt.tv website and Trakt.tv API (version 2.0) had been launched on December 28th, the same day that the number of Trakt.tv API profile page views started to rise. Version 1.0 of the Trakt.tv API was also retired on December 28th — which caught some developers completely by surprise, their Trakt third-party apps now broken. ProgrammableWeb reached out to Justin Nemeth, developer and Trakt co-founder, who provided information about the events surrounding the launch of the new Trakt website and the transition from version 1.0 of the Trakt API to version 2.0.
The Launch of Trakt API 2.0
Trakt is a platform that allows users to keep track of TV shows and movies that they have watched. Users can check in and manually add TV shows and movies that they have watched or they can enable scrobbling. The Trakt platform features scrobbling capabilities (similar to Last.fm) that allow TV shows and movies watched by users to be automatically tracked by the platform. In addition to automatic scrobbling, standard Trakt features include personalized TV and movie recommendations, recently watched widgets, watchlists, and more.
Trakt version 1.0 was a PHP-based app using the CodeIgniter framework that was launched in the summer of 2010 and patched until 2014. Around mid 2014, the Trakt 1.0 website began to experience data integrity and speed issues. Justin Nemeth explained to ProgrammableWeb that:
“It was not uncommon for data loss to occur during peak hours simply because of the extreme load on the site. 20-second website load times were also not uncommon. Simply put, we learned that Trakt 1.0 was reaching its breaking point and could not handle the nearly 800,000 members and 30 million API requests per day.”
The Trakt developers began to plan for Trakt 2.0 in early 2014; however, they had very limited development resources (10-20 hours a week). Due to the limited development resources, the Trakt team decided to focus all of their time on building Trakt 2.0, a re-architected Ruby on Rails app. The Trakt website and API have both been re-coded from the ground up with a strong emphasis on caching. Trakt 2.0 has been designed to be highly scalable and capable of growing to millions of members.
Justin Nemeth explained to ProgrammableWeb that the Trakt team had reached out to developers in several ways to notify them of the upcoming changes to the Trakt platform and API. The Trakt team created a few posts in the old Trakt API Google group (post 1, post 2) and posted several tweets asking developers using the Trakt API to contact Trakt support (tweet 1, tweet 2, tweet 3)
Sometime around June 2014, app developers who had received a special API key with extended permissions were emailed directly (Trakt had gathered email contact info as part of this process) about Trakt 2.0. Trakt also opened a new Google+ Trakt API community at this time.
The Trakt team has been gathering feedback for Trakt API 2.0 since June and has been working closely with many Trakt developers, via direct email and the Google+ community. In addition, plans for Trakt 2.0 and updates about the design and coding process were regularly posted in the Trakt VIP forum. The beta version of Trakt API 2.0 was available on Aug 17th and an announcement was made advising developers that version 1.0 of the Trakt API would continue to exist, but in a limited form.
Despite the efforts of the Trakt team to notify third-party app developers of the upcoming Trakt 2.0 website and API, many developers were caught completely by surprise at the launch of Trakt API 2.0 and the retirement of Trakt API 1.0. Justin Nemeth told ProgrammableWeb that:
“After launching 2.0, it was surprising to hear from so many developers who were not aware of the new API. It was never our intention to leave any developers in the dark. We personally corresponded with hundreds of developers about 2.0, which to our knowledge, represented the large majority of apps out there. Moving forward, the API will be versioned so apps can migrate without functionality loss. We will do a better job of giving developers ample notice for new API versions and changes.”
Differences Between Trakt API 2.0 and 1.0
There are quite a few differences between the Trakt 2.0 and 1.0 API, including (but not limited to):
- Complete code rewrite with heavy focus on caching (server side and CloudFlare)
- New API docs (http://docs.trakt.apiary.io)
- OAuth support
- GET methods don’t mash in user-specific data (so we can cache more effectively)
- Playback API to sync playback across devices (see http://firecore.com/infuse for a live implementation)
- Movie calendars
- Pagination and limits (in 1.0 it would always dump all data in a single, huge call)
- New search service (backed by Solr)
- New recommendation engine (work in progress)
The Importance of an API Deprecation Policy
An API deprecation schedule/table is a great way to communicate to developers about how long an API will be available before it is retired.
Although the Trakt team did make a great deal of effort to contact developers and notify them of the upcoming new Trakt website and API, many developers were still not aware of the impending API changes. The situation with the Trakt API highlights the importance of a clear and concise API deprecation policy that is effectively communicated to developers.
A deprecation policy allows API providers to effectively communicate to API consumers about upcoming changes to an API. An API deprecation policy tells users when and why an API will be retired, how an API will be retired, and explains other API policy changes. An API deprecation policy should include the following:
New Versions of an API Should be Announced in Advance
Ideally an API provider is using an API management system that features automatic developer account and API key creation. This allows developers to quickly and easily create an account, generate an API key, and start using an API right away. An API management system also allows API providers to keep track of developers using an API and gather developer email addresses and other contact information. Upcoming API changes can then be emailed to all developers who have registered to use the API. However, there are some API providers that do not yet offer automatic account creation — account information and API keys are instead provided to developers via email.
While an API provider may have a database that contains email addresses of developers using an API, email addresses can easily change and developer contact information can quickly become outdated. API providers should not rely solely on email to communicate upcoming API changes to developers. Impending API changes should be announced via email, Twitter, social media networks, company blog posts, tech blog posts, developer forums, and other public communication platforms. If an API provider has created a group or forum (public or private) specifically to discuss upcoming API changes, a link should be displayed prominently on the company website, developer portal, and in the API documentation.
Old API Versions Should be Given a “Sunset Period”
Many API providers like Google, Foursquare, Urban Airship, and Twitter have a “sunset period” for their APIs. A sunset period is a set length of time that a deprecated API or deprecated API features will be available to use. The sunset period varies widely among API providers and can last 3 months, 6 months, 1 year, or longer. The sunset period provides developers a set amount of time to upgrade their applications to newer versions of an API as well as prepare for API features that will soon be deprecated.
An API Migration Guide Should Be Provided
A well designed and detailed API migration guide helps developers understand the upcoming changes to an API and includes the steps needed to migrate an app to the latest version of an API. A good migration guide should also include tables that clearly show changes to specific web services and components, an endpoints status map, and any other information that will help developers migrate their apps to a new version of an API.
Publish an API Deprecation Schedule/Table
An API deprecation schedule/table is a great way to communicate to developers how long an API will be available before it is retired. Facebook, Urban Airship, and Google all offer easy-to-read API deprecation schedules/tables for their APIs. The Google deprecation schedule/table even includes a link to an API migration guide.
Use HTTP Status Codes
The Foursquare API returns HTTP status codes with additional details provided in the errorType. Responses to requests using deprecated Foursquare API versions and endpoints will include an errorType of deprecated and will also contain useful information in the meta section of the API response. This is another good way to communicate API changes to developers.
Communication with developers is crucial throughout the API development lifecycle, particularly when an API has been sunsetted and is on its way to retirement. A clear and concise API deprecation policy helps an API provider build trust with developers and third-party app users by effectively communicating impending API changes so that developers will have the time needed to upgrade their applications.
As for Trakt, the transition from Trakt API 1.0 to 2.0 has been rough for some Trakt third-party apps. Others, however, have been able to successfully upgrade to the new Trakt API including Movist, Infuse, MediaPortal, Plex, and checkTrakt.
“We’ve learned a lot through this process to help us communicate more efficiently with the entire Trakt community moving forward.” said Justin Nemeth. “We knew the Trakt community was passionate, but the 2.0 launch has shown us just how important Trakt has become in the social TV ecosystem. We are committed to growing Trakt into the community our members and developers deserve. I have been full time on Trakt for about 6 weeks and couldn’t be happier.”
For more information about the new Trakt platform and API, visit Trakt.tv