Programmatically consuming Heroku services
With Heroku Platform API, Heroku provides you with the ability to call the Heroku platform services to do virtually anything you need to do on Heroku—creating an application, checking the release history of your app, or plugging new add-ons in to your application. All this and more just by using simple HTTP. The following diagram depicts the interaction between a simple Heroku API client and the Heroku platform services. An API client can use the Heroku API to interact the core platform services of Heroku using a well-defined interface.
The Heroku Platform API allows you to do almost everything you can do with the Heroku command line or dashboard. This API is a powerful tool for application developers to leverage the capabilities of Heroku's features and gain complete control of their apps, from creating to monitoring them.
The Heroku Platform API
There are at least three important components of the Heroku Platform API as shown in the following diagram. These components define the behavior of the API to the external world.
The components are:
- Security
- Schema
- Data
Any application that wants to consume services provided by the Heroku platform via the Platform API should authenticate the users trying to access the service. Though basic HTTP authentication would work, if you are using your own scripts and don't expect to expose those to a wider audience, OAuth is the recommended way to provide authentication support for third-parties to access Heroku services. You can use the OAuth token to provide access to your account to every user including third parties. By gaining access through OAuth, third parties can then use your applications to provide many value added services such as monitoring, scalability, or application management.
To use the Platform API, the client needs to know a few things. For example, what resource is available, what is the corresponding resource location, how this resource is represented, and what operations are allowed on the resource? Only then a client can create a request to access the details of the resource as available on the Heroku platform via the API. Much of this information is provided by the API schema. This schema stored in the JSON format is machine readable and describes various aspects of the resource. The API schema, like other API resources, can also be accessed using the curl utility. Heroku also supports the validation and hypertext extensions for the base JSON schema to enable more powerful manipulation of the JSON data.
Whenever the client receives a response from the Heroku Platform API, the response header contains the Entity tag (ETag). This tag is used to identify the precise version of the resource accessed, just in case the resource is needed again later. This ETag can be embedded inside the If-Not-Match header field in future requests to verify that the resource has indeed changed. If the resource hasn't changed, a return status of not modified is sent back to the client. If the resource has changed since the earlier request, the call performs normally and returns the new characteristics of the resource.
You can optimize the resource access by caching the resource response at the client side and issuing an API request for the resource only when the resource is indeed changed on the platform side.
Accessing the API
The client using the platform API calls standard methods defined for HTTP and passes parameters in the request body to the serving API. The API acts on the request, performs the specific operation, and returns results of the operation to the client via a response that is a JSON representation of the details of the resource requested.
Since the Heroku Platform API was recently released in Beta, API clients written in various languages that Heroku supports are slowly emerging on the development scene. Heroku supports an API client called Heroics for Ruby and there are more that have come up. There are known API clients for Node.js, Scala, and Go that could be used based on your app requirements.
API clients address the requests to api.heroku.com using HTTPS and specify the Accept: application/vnd.heroku+json; version=3 Accept HTTPS header in the request. The client can also specify a User-Agent header to help with troubleshooting and tracking the request if required.
For the most part, you can use curl (http://curl.haxx.se/) as an API client in scripts or utilities to call the Heroku Platform API. The calling convention to access the Platform API is simple and the returned results are in the JSON format, so parsing and using them is very straightforward.
For other programming languages, all you need is a HTTP library and methods to call the API from your code and you are all set. Call the API, receive the returned data, parse it, and use it in your application. In this section, we use curl to show some samples to give you a basic understanding of how to invoke the API.
The success or failure of the Platform API call is indicated by the status code returned by the API on completion. The API call can result in various actions, for example, the creation of a resource as in the case of a new application getting created or reviewing the history of a resource, for example, looking at the revision history of an application.
The API response is comprised of the shorter, relevant part of the HTTP header and the response details in the JSON body if required. The response header includes the current count of the remaining allowed API requests for the account.
The Heroku platform API allows the developer to control various aspects of the Heroku application development from within the application. The developer can manage application configuration, runtime (dynos), deployment, and user account management, besides a wide array of other functions. However, the platform puts a restriction on the number of API calls a user or developer can make per hour. This is essentially to protect against unnecessary overuse, ensure fair response handling of innumerable clients, and enforce security measures. With each API call, this token count is decremented.