Heroku's API team has spent a large part of the past year designing a new version of the platform API. While this is the 3rd incarnation of the API, neither of the two previous versions were publicly documented. In fact, the only documentation on the old APIs that was ever published is the source code of the Heroku Rubygem, which powers the Heroku Toolbelt. That worked fairly well at the time for Heroku's Ruby-centric audience, but it was never ideal, especially since Heroku's developer audience now uses many languages besides Ruby.

Additionally, the first two "versions" of Heroku's API were developed organically as the platform's capabilities evolved, with contributions made by many engineers over the years. The API was built primarily as an interface for the toolbelt, rather than as a product. It was also not properly versioned, as there was no process for managing changes publicly. And because the API was not treated as a product in and of itself, the old APIs are scarred by numerous inconsistencies and lack coherence.