Today, we’re happy to announce General Availability of the Heroku Platform API. Heroku is a platform built by developers, for developers. As developers, we understand the utility of APIs and the power APIs give to speed up and script error-prone manual processes or to combine other services with Heroku into new and exciting products. With the Platform API, you now have a fully documented and supported way to instrument and automate Heroku.
Designing and implementing this API has been an important process for Heroku internally: It has forced us rethink how different platform components are factored and how they should be exposed in a clean and coherent manner. We are already using the Platform API heavily for projects at Heroku, and the new API is superseding and replacing the spread of private and semi-public APIs that have made Heroku work so far.
Because platform functionality is now available in a single API that has good documentation and updated client libraries, Heroku can create better products and services, faster. By making the API public, we want to give Heroku customers, users, and partners the same opportunity.
Readers new to the Platform API can jump straight to the quickstart to get started.
APIs are hard
Building and maintaining APIs for the long haul is hard. As an API evolves, documentation has to be kept in sync and client libraries for supported languages must be updated to take advantage of new features. To make those tasks easier for ourselves, Heroku publishes a single canonical JSON schema that is used to generated the artifacts necessary to consume the Platform API, including Reference Documentation and client libraries for Ruby, Go, Scala and Node.
UPDATE: Check out this follow-up blog post on the Heroku HTTP API Toolchain we have built to manage this process.
Another difficult aspect of API maintenance is managing and communicating changes. To address this, we have recently added stability attributes to the JSON schema for the Platform API. Stability is also surfaced in the reference doc on Dev Center. For any given endpoint, stability can be either prototype, development or production. The stability of an endpoint communicates how “done” the endpoint is. A prototype endpoint will likely see many changes or may not make it to production. A production endpoint, on the other hand, is done and will not see breaking changes unless the underlying feature is deprecated (which will be communicated with at least 12 months warning).
All API endpoints that expose core Heroku concepts (such as account, app and add-on) are of production stability. Heroku users and partners can incorporate these API endpoints into their workflows and services safe in the knowledge that the API will not change or go away without due warning.
Heroku also publishes all API changes to the Changelog and we recommend subscribing for updates.
Looking ahead
The past year has been a busy one for the Platform API. The beta launched last May, OAuth came in July and we have been adding endpoints and methods at a rapid clip since. To get an idea of what we’re currently working on, you can skim the reference docs and look for prototype and development endpoints.
To get started with the Platform API, check out the Getting Started Guide. For personal experiments and scripts used to manage apps on your account, we recommend using the API key found on your account page in Dashboard. You can also generate additional keys for experiments using the API. The Platform API also has beta support for OAuth, but we have not yet perfected the OAuth scopes nor how token access is scoped to endpoints exposed in the API.
We are also looking at combining the Platform API with the API that most Heroku partners currently use to integrate with Heroku: The Add-on provider API. Until we have completed this task, OAuth clients can have tokens issued for at most 100 Heroku accounts. If you are building an OAuth-enabled service on the Platform API and expect that it will get wide distribution, we ask that you contact us to discuss a partnership.
We are always keen to hear user’s thoughts on what we build. For API feedback, get in touch at api-feedback@heroku.com.