Creating Heroku Addons: Getting Started
Recently the Loggly add-on went live for all Heroku users. Creating this add-on involved implementing a few API endpoints in our service for Heroku to call. This is a quick overview of what the development process looks like.
Heroku's add-on API specs have a number of calls that fall into the following three categories:
- Provisioning/deprovisioning: These are calls that ask the add-on service to create or remove resources on behalf of the Heroku user. One thing to remember here is that Heroku will ask the add-on service to create resources per Heroku *app*, not per Heroku user account.
In most cases, when Heroku makes a provisioning call to the add-on service, a new account is created for a Heroku app. - Single-sign-on: Heroku users do not need to provide separate account credentials to access services the add-on provides. As long as they are logged into Heroku, they are able to use or configure the add-on. This is accomplished by forwarding the user to the add-on's URL. A token and a timestamp are forwarded along with this request for authentication.
- Plan change: Heroku allows add-on providers to change users based on tiers of service. A Heroku user is free to upgrade or downgrade add-on tiers at any time.
Each of these required actions corresponds to a REST endpoint that the add-on service
must implement:
- POST and DELETE to http://<addon_service>/heroku/resources respectively provision and deprovision accounts.
- GET to http://<addon_service>/heroku/resources/<id>?token=<token>×tamp=<timestamp> does authentication and any necessary forwarding for SSO.
- UPDATE to http://<addon_service>/heroku/resources/<id> will update the account's service tier.
Heroku provides an awesome tool called kensa that simulates API calls from Heroku on these endpoints to test the add-on service.
To install kensa open up a terminal and make sure you have Ruby and gems installed and type:
sudo gem install kensa
Kensa is used to generate the boilerplate manifest that describes properties of the add-on:
Brasero:blogpost ivan$ kensa init
Initialized new addon manifest in addon-manifest.json
Brasero:blogpost ivan$ cat addon-manifest.json
{
"id": "myaddon",
"api": {
"config_vars": [ "MYADDON_URL" ],
"password": "QQMmzfm3pkzzE3Fn",
"sso_salt": "eqs5xOh7kGqen5hd",
"production": "https://yourapp.com/",
"test": "http://localhost:4567/"
}
}
Edit the id to name the add-on. Edit the test and production urls to reflect the hostnames of your respective test and development hosts.
Heroku doesn't call it as such, but kensa is also a tool that cleverly puts test-driven development into your add-on development process. When you run the tool in test mode, it makes REST calls to the host defined in the test directive of the addon-manifest.json file:
Brasero:workspace ivan$ kensa test provision
Testing manifest id key
Check if exists [PASS]
Check is a string [PASS]
Check is not blank [PASS]
Testing manifest api key
Check if exists [PASS]
Check is a hash [PASS]
Check contains password [PASS]
Check contains test url [PASS]
Check contains production url [PASS]
Check production url uses SSL [PASS]
Check contains config_vars array [PASS]
Check containst at least one config var [PASS]
Check all config vars are uppercase strings [PASS]
Check all config vars are prefixed with the addon id [PASS]
Check deprecated fields [PASS]
done.
Testing POST /heroku/resources
Check response [FAIL]
! expected 200, got 401
The output above is typical from early runs of kensa, but by running the kensa tool early and often the test failures will guide development.
After all the provision tests pass, invoke the next set of tests for deprovisioning by running:
Brasero:workspace ivan$ kensa test deprovision <some account id>
Follow through with the planchange, and sso tests. When all tests pass, the integration is complete!
What remains is to upload addon-manifest.json to your Heroku provider account and to document the add-on for the Heroku Addon Catalog. More information on how to do that is available here.
Other tips:
- Until the add-on leaves Beta, the only plan available to test is the test plan. Be sure your add-on has a test plan during development.
- Don't go into Beta until the add-on is feature complete. An add-on cannot be taken out of Beta back into Alpha without help from Heroku.
sandip 2 Dec, 2011 05:46am
IS there any tutorial on how to implement it in rails framework?
Testing POST /heroku/resources
heroku documentation shows it for sinatra framework