Add-on Provider API

Last Updated: 08 May 2015

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

When a user requests the installation of an add-on, Heroku will make a POST request to your API at /heroku/resources with the following body:

{
  "heroku_id": "app1234@heroku.com",
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "callback_url": "https://api.heroku.com/vendor/apps/app1234@heroku.com",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "logplex_token": "t.01234567-89ab-cdef-0123-456789abcdef",
  "options": {},
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}

Your service MUST respond with valid JSON. At minimum, this response body must include an id field with an identifier for the installed add-on that is unique to this request across your entire service.

In the provision request, only the uuid field is guaranteed to be unique and stable. It it is extremely important that you do not return to Heroku an id based on Heroku-sent fields, other than the uuid field.

You MAY also include a message to be displayed to the user with further instructions and a config object with environment variables to be set on any applications that use this add-on.

For some add-ons, the actual environment variable set on an application may be different than the key in this hash. We will strip the config variable prefix from each key and use it as the default prefix for applications using the add-on. However, the user may choose a different prefix.

For example, if your add-on is named fast-db and you are setting FAST_DB_URL, the variable name on the application will default to FAST_DB_URL but would be PRIMARY_DB_URL if the user added the add-on with the prefix PRIMARY_DB.

{
  "id": "your-internal-unique-id",
  "config": {"MYADDON_URL": "http://myaddon.com/52e82f5d73"},
  "message": "your message here"
}

The heroku_id field is an identifier for the application which will own the add-on being provisioned. It does not uniquely identify the add-on itself. For this, please refer to the uuid field.

The callback_url is the URL which should be used to retrieve updated information about the add-on and the app which owns it.

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 uuid field is the unique identifier Heroku uses for the installed add-on. It corresponds with the id field in the Heroku Platform API.

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:create 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:create 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

When a user requests a plan change for an installed add-on, Heroku will send a PUT request to your API at /heroku/resources/:provider_id with the following body:

{
  "heroku_id": "app1234@heroku.com",
  "plan": "plan-name"
}

The heroku_id field contains an identifier for the application that owns the add-on. The ID in the request URI (:provider_id) must be used to identify the add-on to manipulate, as heroku_id is not guaranteed to be unique.

The plan field will correspond to the plan identifier set in the Provider Portal.

Your service MUST respond with a 2xx status code for successful plan changes with a valid JSON body (it may be the empty object {}).

You MAY include a message field, which will be displayed to the user, and a config object (as per the Provision call) if you wish to update their values during plan change. You may also update those values asynchronously using the App Info API.

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. For example, if it is impossible to change between the users current plan and the requested plan, a 422 status code with a explanatory message is appropriate. However, if the plan change is failing due to internal reasons and the user should try again later, a 503 may be more appropriate.

Deprovision

When an add-on is removed from a user’s account, Heroku will make a DELETE request to your API at /heroku/resources/:provider_id.

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

If your API can not fulfil a request, you should respond with an appropriate HTTP status code in the 4xx range if it is due to an invalid request (e.g. non-existent plan) or 5xx range if your API is experiencing unexpected errors. The response body MUST contain valid JSON.

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 an add-on dashboard via SSO by directing them to

https://api.heroku.com/myapps/<heroku_app_id>/addons/<uuid from provision request>?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.