Today, we are excited to release our new platform API into public beta, turning Heroku into an extensible platform for building new and exciting services. Our platform API derives from the same command-and-control API we use internally, giving entrepreneurs and innovators unprecedented power to integrate and extend our platform. Some of the uses we’ve imagined include:
- Building mobile apps that control Heroku from smartphones and tablets;
- Combining Heroku with other services and integrating with developer tools;
- Automating custom workflows with programmatic integration to Heroku
The platform API empowers developers to automate, extend and combine Heroku with other services. You can use the platform API to programmatically create apps, provision add-ons and perform other tasks that could previously only be accomplished with Heroku toolbelt or dashboard.
Getting Started
The Heroku platform API uses HTTP and JSON to transfer data and is simple enough to experiment with using cURL. The examples below use the -n switch to read credentials from the ~/.netrc file, which is created automatically if you are using toolbelt.
First, create a new Heroku app by sending a POST request to the /apps endpoint:
$ curl -n -X POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"
{
…
"name":"mighty-cove-7151",
…
}
This is equivalent to running $ heroku create or creating an app in dashboard. The platform API uses the mime type provided in the accept header to determine which version to serve. Version 3 is the first publicly available version. Prior versions were internal only.
Now provision the Postgres add-on for use with the created app:
$ curl -n -X POST https://api.heroku.com/apps/mighty-cove-7151/addons \
-H "Accept: application/vnd.heroku+json; version=3" \
-d “{\”plan\”:{\”name\”:\”heroku-postgresql:dev\”}}”
This is the same as running $ heroku addons:add heroku-postgresql:dev -a mightycove-7151 or adding an add-on in dashboard. You can use the API to add any available add-ons and to perform other app setup tasks such as scaling and adding configuration vars. Using the API, you can automate the process of going from new to fully configured app with ease.
These two examples barely scratch the surface of what’s possible. For more details on using the platform API, refer to the quickstart and reference documentation.
The Future
Over the coming weeks and months, while the platform API is in public beta, we will collect and incorporate feedback. During the public beta, we may introduce breaking changes to the API. All changes will be posted on the changelog.
Providing Feedback
The goal of the public beta is to collect and incorporate feedback. Please send feedback to api-feedback@heroku.com. We’re especially interested in your thoughts on the following:
- What do you think of the overall design?
- Is there anything missing for your use case?
- How can we make the API easier to use?
If you have questions about using the new API, please post them on Stack Overflow with the heroku tag.
We hope you like what you find and look forward to your exploration and innovation on top of the Heroku platform.