Add-on Provider API

Last Updated: 10 December 2014

add-ons api

Table of Contents

The Add-on Provider API is used when Heroku calls your add-on service. In these examples Heroku is issuing the requests and your add-on is providing the responses.

General guidelines

All calls should be protected by HTTP basic auth with the add-on id (sometimes called the add-on identifier or slug) and password specified in your add-on manifest.

All calls are required. Any requests that are unable to be serviced should return a 422 response with an informative message for the user.

Your service should respond within 3 seconds. Currently, it must return within 25 seconds or the request will fail. This upper limit will be reduced over time at our discretion and based on our analysis.

If longer work is necessary, respond 202 Accepted as an acknowledgement that the provision will be fulfilled and use the App Info API to set any necessary config vars when ready. The app will be restarted accordingly.

Provision

Request: POST https://username:password@api.youraddon.com/heroku/resources
Request Body: {
  "heroku_id": "app123@heroku.com",
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "callback_url": "https://api.heroku.com/vendor/apps/app123%40heroku.com",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "options": {}
}
Response Body: {
  "id": "your-internal-unique-id",
  "config": {"MYADDON_URL": "http://myaddon.com/52e82f5d73"},
  "message": "your message here"
}

If you wish to access information which can change (e.g., owner email address or application name) then it is available via the App Info API. The App Info API will return a 4XX response until you’ve returned a successful provisioning response to Heroku. As a result, we recommend accessing it asynchronously after provisioning. It is the responsibility of the provider to periodically check this endpoint to ensure data is consistent.

The region attribute in the request specifies geographical region of the app that the add-on is being provisioned to—either amazon-web-services::us-east-1 or amazon-web-services::eu-west-1 are possible at this time. Use this to provision the resource in geopgraphical proximity to the app, ignore it (if your add-on is not latency sensitive) or respond with an error if your add-on does not support apps in the region specified.

The log_input_url attribute is provided so that logs can be sent to the app’s log stream. This field is only present when configured in you manifest, by adding log_input to the requires field. For more information, see the article describing logplex input. The logplex_token attribute used to be used for this purpose, but is deprecated and will be removed in the near future.

The options object in the request are extra command line options passed in to the heroku addons:add command.

The id value returned in the response may be a string (e.g. UUID) or integer value. It should be an immutable value that can be used to address the relationship between this app and resource. This means that a plan change can not change the value of this id, although you can update the config later to point the app to a different resource.

The config object and message in the response are both optional.

Heroku can also pass command-line parameters given to the addons:add action during add-on provisioning to the add-on provider. Providers that require access to advanced features will receive additional attributes based on the features they’ve requested.

Plan change

Request: PUT https://username:password@api.youraddon.com/heroku/resources/:id
Request Body: {"heroku_id": "app123@heroku.com", "plan": "premium"}
Response Body: {"config": { ... }, "message": "your message here"}

The config object and message in the response are both optional. The response should always be valid JSON, even if only the empty object {}.

If you can not support plan changes, respond with status code 422 or 503 and return a message to display to the user, as per the description below.

Deprovision

Request: DELETE https://username:password@api.youraddon.com/heroku/resources/:id
Request Body: none
Response Status: 200
Response Body: {}

The response should be valid JSON, even if only the empty object {}.

You may also return a 204 No Content status with an empty body for this particular request.

Exceptions

Request: https://username:password@api.youraddon.com/
Request Body: any
Response Status: 422
Response Body: { "message": "your message here" }

For 4xx and 5xx responses on provision and plan change requests, the message property from your JSON response will be displayed to the user. For all other responses, and when no message property is available, a generic error message will be displayed.

For common types of errors, it is recommended that your API add an id property to error payloads that contains a short keyword identifying the type of error. For an example, see how Heroku does it in our Platform API Reference. In the future, such identifiers may be exposed to providers in metrics and tooling for analysis.

Single sign-on

Request: POST https://username:password@api.heroku.com/sso/login/
Request Body: id=<id>&token=<token>&timestamp=<ts>&nav-data=<data>&email=<user-email>&app=<app-name>&other=vals
Response Header: Set-Cookie: heroku-nav-data=<data>
Response Body: Web view for logged-in user

Optional values can be passed through by appending them to the Heroku API SSO URL. Users can be automatically logged in to and add-on dashboard via SSO by directing them to

https://api.heroku.com/myapps/<heroku_app_id>/addons/<addon-name>?other=vals

See manifest formats for more information about configuring single sign-on.

App Info API

After your addon is provisioned, you can use the App Info API to query information about your addon installations or to update the Config Vars for your addon.