Haiku API

Intro

We have developed the newest version of our Add-Ons API to be compatible with Heroku's Add-Ons API. If you have already created an add-on for Heroku, it should be minimal work to setup your add-on for use by Engine Yard customers. Please review the documentation below as it is noted where there are differences between our API and Heroku's and what is needed to accommodate those differences.

If you have not previously created an add-on for Heroku, then please follow the instructions below in order to get started.

Creation

Registration and Manifest

To create an Add-on you must first submit some basic information known as a manifest.

You can construct this request yourself using the URL in the example. This request requires HTTP Basic Auth using your partner-specific auth_id and auth_key as username and password.

Instead of constructing this request, you could use kensa, for example:

ADDONS_URL=https://addons.engineyard.com kensa push

You can also submit your manifest directly using the Partner Portal web UI.

Add-ons can be updated by re-pushing your manifest. If the id of your manifest matches an existing Add-on you own, the Add-on will be updated.

Request Parameters

Name	Description
`id`	Name for your service in URLS and ey_config (whats users use to access vars you expose)
`config_vars`	(optional) vars you plan to expose in response to activate API calls
`regions`	(ignored) exists only for compatability with the publish heroku API
`password`	Combined with `id` this will be used to authenticate communications between Engine Yard and your Add-on (using HTTP Basic Auth)
`sso_salt`	Used to authenticate SSO requests (see SSO documentation below)
`production`	Specify urls relevant for your Add-on as it will be when deployed to production
`base_url`	The URL Engine Yard will POST to when a user activates your Add-on
`sso_url`	The URL Engine Yard will POST to initiate SSO (see SSO documentation below)
`test`	(ignored) used by kensa tool to test your Add-on

Example Request

Headers

Accept: application/json
Date: Sun, 16 Feb 2014 00:01:17 GMT
Content-Type: application/json
Authorization: Basic MGMxY2U0MTIwYjRlMTdiNDpjYWZmNDhhNTRlMTQxMDYxZDAyZmVjNGZmZTJi
ZjI2ODk1NmM4NGFiOThkMTMxZDVkYzQ5NzZlNGIxMzNjNjFiMjViYTkzODRm
ZGRmNmRhZg==

Route

POST https://addons.engineyard.com/provider/addons

Body

{
  "id": "mockservice",
  "api": {
    "config_vars": [
      "FOO",
      "BAR"
    ],
    "regions": [
      "us"
    ],
    "password": "3204df9fdff8233f45e3aeb0e81b0cd71cf93583f1bbbaa3f4109bb155ee5f57",
    "sso_salt": "c607beb7366480bc546c2f25e6e9958161a761076196aeafdd768f5a6f3bf75f",
    "production": {
      "base_url": "http://mock.service/heroku-style-api/resources",
      "sso_url": "http://mock.service/heroku-style-sso/login"
    },
    "test": {
      "base_url": "http://localhost:5000/heroku-style-api/resources",
      "sso_url": "http://localhost:5000/heroku-style-sso/login"
    }
  }
}

Example Response

Headers

Content-Type: text/plain; charset=utf-8

Status

Body

ok

Activation

When a user activates your Add-on in the Engine Yard UI, this API call is made to your Add-on.

Request Parameters

Name	Description
`ey_id`	A Unique ID for the activation event
`name`	A name that may be useful if you are creating something for the user. For example: database name, account name, etc.. (not guaranteed to be unique)
`heroku_id`	The previous 2 paramters concatenated (provided for compatability with the Heroku API)
`plan`	The `api_name` of the plan selected by the user
`region`	(ignored) provided for compatability with the Heroku API
`callback_url`	An API URL specific to this activation that the Add-on can use for more information
`options`	(ignored) Always an empty hash, provided for compatability with the Heroku API
`invoices_url`	URL to post additional charges to (see advanced docs: Invoicing)

Response Parameters

Name	Description
`id`	A Uniqe ID provided by the Add-on for this activation (will be referenced for updates and deletes)
`config`	The set of vars to expose in the user's app
`message`	(ignored) provided for compatability with the Heroku API

Example Request

Headers

Accept: application/json
Date: Sun, 16 Feb 2014 00:01:18 GMT
Content-Type: application/json
Authorization: Basic bW9ja3NlcnZpY2U6MzIwNGRmOWZkZmY4MjMzZjQ1ZTNhZWIwZTgxYjBjZDcx
Y2Y5MzU4M2YxYmJiYWEzZjQxMDliYjE1NWVlNWY1Nw==

Route

POST http://mock.service/heroku-style-api/resources

Body

{
  "ey_id": 1,
  "name": "mockservice_helloworld_production_helloworld",
  "invoices_url": "https://addons.engineyard.com/api/2/provisioned_services/1/invoices",
  "callback_url": "https://addons.engineyard.com/api/2/provisioned_services/1",
  "plan": "test",
  "heroku_id": "1-mockservice_helloworld_production_helloworld",
  "region": "NA",
  "options": {
  }
}

Example Response

Headers

Content-Type: application/json

Status

Body

{
  "id": 1,
  "config": {
    "FOO": "bar"
  },
  "message": "Dear customer, your addon is now provisioned!"
}

SSO

When a user clicks on the link to 'Dashbaord' for your Add-on after activation, Engine Yard will redirect to the sso_url from your manifest.

It will do so with POST request, with a set of form-encoded params giving you more information about the Add-on activation and the user.

To verify an SSO request calculate the SHA1 hash in hex of the pre_token and compare it with the token. Calculate pre_token as the concatenation of id, sso_salt and timestamp with a colon character (:).

Here is an example in Ruby:

pre_token = params[:id] + ':' + SSO_SALT + ':' + params[:timestamp]
token = Digest::SHA1.hexdigest(pre_token).to_s
halt 403 if token != params[:token]

Engine Yard customers will be able to access your add-on's admin panel. However, unlike Heroku, we will not render an Engine Yard navigation bar. Therefore, if you are utilizing an add-on built for Heroku, you will need to remove all references to nav-data. We are investigating if and when to introduce navigation bars in the future.

Request Parameters

Name	Description
`app`	The name used during activation (provided for compatability with heroku, can be ignored)
`email`	The e-mail address of the user
`ey_return_to_url`	A URL you can send the user back to if you wish to display a "Return to Engine Yard" link
`id`	IMPORTANT! The ID of the Add-on Activation (as provided by the Add-on in the response to Activation)
`timestamp`	timestamp of the SSO request
`token`	Use this in combination with the timestamp and sso_salt to verify the request

Example Request

Headers

Content-Type: application/x-www-form-urlencoded

Route

POST http://mock.service/heroku-style-sso/login

Body

email: tftesting@engineyard.com
app: mockservice_helloworld_production_helloworld
id: 1
ey_return_to_url: https://addons.engineyard.com/addons/addons/1
timestamp: 1392508878
token: 42b315079a9214a8d272f979e28e5b34f482415b

Example Response

Headers

Content-Type: text/html;charset=utf-8
Location: http://mock.service/

Status

Body

Plan Change

When a user changes plans, Engine Yard will make an API request to update the Add-on activation.

The url is constructed as the base_url of your Add-on plus the id of the Add-on activation.

Engine Yard will perform all the necessary computations to bill the customer a pro-rated amount for the previous plan.

Request Parameters

Name	Description
`plan`	The `api_name` of the new plan

Example Request

Headers

Accept: application/json
Date: Sun, 16 Feb 2014 00:01:19 GMT
Content-Type: application/json
Authorization: Basic bW9ja3NlcnZpY2U6MzIwNGRmOWZkZmY4MjMzZjQ1ZTNhZWIwZTgxYjBjZDcx
Y2Y5MzU4M2YxYmJiYWEzZjQxMDliYjE1NWVlNWY1Nw==

Route

PUT http://mock.service/heroku-style-api/resources/1

Body

{
  "plan": "premium_api_name"
}

Example Response

Headers

Content-Type: text/html;charset=utf-8

Status

Body

ok

Vars Update

It may be necessary at times to udpate the vars for an Add-on activation.

You may do by making a PUT request to the callback_url provided at the time of activation.

For example, when the user performs SSO to access the Add-on there may be a button like 'reset database password'. If database password is something exposed via vars, you should send an update to Engine Yard via this API call.

It's important to note that the user's app won't automatically be updated when you do this, the user must still perform a deploy to receive the new vars. So, if possible, it's a good idea to give them a grace period in which both the old and new vars work, and inform of them of this period explicitly in the UI and perhaps by sending an e-mail. Something on the order of hours is probably sufficient.

Request Parameters

Name	Description
`config`	The new set of vars for this Add-on activation. If you provide multiple vars but only changed the value of one, be sure to send the full set anyway.

Example Request

Headers

Accept: application/json
Date: Sun, 16 Feb 2014 00:01:19 GMT
Content-Type: application/json
Authorization: Basic bW9ja3NlcnZpY2U6MzIwNGRmOWZkZmY4MjMzZjQ1ZTNhZWIwZTgxYjBjZDcx
Y2Y5MzU4M2YxYmJiYWEzZjQxMDliYjE1NWVlNWY1Nw==

Route

PUT https://addons.engineyard.com/api/2/provisioned_services/1

Body

{
  "config": {
    "FOO": "bar baz"
  }
}

Example Response

Headers

Content-Type: text/plain; charset=utf-8

Status

Body

ok

De-Activation

If a user choose to De-activate you Add-on the Engine Yard UI, this API call will be made to you Add-on.

The url is constructed as the base_url of your Add-on plus the id of the Add-on activation.

Example Request

Headers

Accept: application/json
Date: Sun, 16 Feb 2014 00:01:19 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bW9ja3NlcnZpY2U6MzIwNGRmOWZkZmY4MjMzZjQ1ZTNhZWIwZTgxYjBjZDcx
Y2Y5MzU4M2YxYmJiYWEzZjQxMDliYjE1NWVlNWY1Nw==

Route

DELETE http://mock.service/heroku-style-api/resources/1

Body

Example Response

Headers

Content-Type: text/html;charset=utf-8

Status

Body

ok