The Sonnet API is designed to accommodate a variety of use cases and Add-ons types. As you read this documentation, think of the API as a tool to help you build a user-experience and workflow for signing up for you Add-on.
One particular powerful part of this api is the ability to set configuration_required on some API responses.
Setting this to true triggers an automatic redirect to your Add-on via SSO.
Add-on Partners typically take advantage of this in order to take control of signup experience,
showing the customer YOUR plan selection page instead of the one on Engine Yard.
This gives you more flexibility, but it may also be more work.
You'll also have to ensure that your system is capable of sending API calls to Engine Yard for each customer at the end of each month for the amount they owe.
Engine Yard does not keep track of which plan is selected with the Sonnet API.
The HMAC-request signing mechanism used by this API has been know to trip up a few developers, so I may be worth starting there.
If you can use Ruby, it's been taken care of for you as part of the ey_services_api Ruby gem.
If not, checkout the code for ey_api_hmac.
You can test you HMAC signing on a simple GET request to your service registration_url.
Sonnet-style Add-ons may only be created via the API.
Make a POST request to the appropriate registration_url including a few bits of information.
Sign the request with HMAC using Partner-specific auth_id and auth_key.
More details on HMAC signing can be found in the ey_api_hmac Ruby gem.
| Name | Description |
|---|---|
name |
Name for your service (TODO: deprecate this paramter in favor of relying on service docs) |
label |
Name for your service in ey_config (whats users use to access vars you expose) |
service_accounts_url |
IMPORTANT: The URL for your Add-on to which Engine Yard will POST to create accounts |
| Name | Description |
|---|---|
name |
The name of your service as you submitted it (TODO: deprecate) |
label |
Name for your service in ey_config (whats users use to access vars you expose) |
home_url |
(Deprecated) provided only for backward-compatability |
service_accounts_url |
The URL for your Add-on to which Engine Yard will POST to create accounts |
service_accounts_listing_url |
URL for getting a list of accounts on your Add-on |
terms_and_conditions_url |
(Deprecated) provided only for backward-compatability |
vars |
(Deprecated) provided only for backward-compatability |
description_html |
(Deprecated) provided only for backward-compatability |
description |
(Deprecated) provided only for backward-compatability |
url |
The URL of your service, may be used to PUT updates of DELETE your service entirely |
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:40 GMT
Content-Type: application/json
Authorization: AuthHMAC be21181efd39b23f:KpMsAGiZU1O2tXNc++0exNLdMRE=
POST https://addons.engineyard.com/api/1/partners/1/services
{
"service": {
"name": "Mock Service 50",
"label": "mock_service",
"service_accounts_url": "http://mock.service/api/1/service_accounts_callback"
}
}
Content-Type: application/json; charset=utf-8
Location: https://addons.engineyard.com/api/1/partners/1/services/1
201
{
"service": {
"name": "Mock Service 50",
"label": "mock_service",
"home_url": null,
"service_accounts_url": "http://mock.service/api/1/service_accounts_callback",
"vars": null,
"description_html": null,
"terms_and_conditions_url": null,
"description": null,
"url": "https://addons.engineyard.com/api/1/partners/1/services/1",
"service_accounts_listing_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts"
},
"url": "https://addons.engineyard.com/api/1/partners/1/services/1"
}
The user will click "Set it up" on your Add-on to create an account with you. This allows the customer to SSO to your site and for you to bill the customer, but it does not expose any vars.
For Add-ons that don't need to integrate at the level of config vars, it's OK to skip implementing the Activation endpoints.
This API call will be made to the service_accounts_url specified in service registration.
| Name | Description |
|---|---|
id |
Id that uniquely identifies the account being created |
name |
The name of the user's account in the EY system (note an account name can change and is not guaranteed to be unique) |
url |
The URL representing the account being created by the API call in the EY system |
messages_url |
(Deprecated) provided only for backward-compatability |
invoices_url |
The URL to POST invoices to charge this user for services |
provisioned_services_url |
The URL representing the set of activations for this account |
| Name | Description |
|---|---|
provisioned_services_url |
The URL EY should POST to for activation on this account |
url |
The URL representing this account in the Add-on (used to cancel the account by DELETE to this url) |
configuration_url |
The URL to use for the user to SSO over to the Add-on account |
configuration_required |
a true or false value. if set to true the user will be immediately redirect over SSO after creating the account. |
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:41 GMT
Content-Type: application/json
Authorization: AuthHMAC be21181efd39b23f:90kdZrOqWT6XBmhr1IZHlLv9SeQ=
POST http://mock.service/api/1/service_accounts_callback
{
"id": 1,
"name": "testing-tf",
"url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1",
"messages_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/messages",
"invoices_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/invoices",
"provisioned_services_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services"
}
Content-Type: application/json
200
{
"service_account": {
"provisioned_services_url": "http://mock.service/api/1/account/1/provisioned_services_callback",
"url": "http://mock.service/api/1/account/1",
"configuration_url": "http://mock.service/sso/account/1",
"configuration_required": false
}
}
After creating an account, the user will activate the Add-on for a specific app-environment, or simply by name.
This API call will be made to the provisioned_services_url specified in response to account creation.
| Name | Description |
|---|---|
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) |
url |
The URL representing this activation in the Engine Yard system |
messages_url |
(Deprecated) provided only for backward-compatability |
environment |
(Deprecated) provided only for backward-compatability |
app |
(Deprecated) provided only for backward-compatability |
| Name | Description |
|---|---|
vars |
The set of vars to expose in the user's app |
configuration_url |
The URL to use for the user to SSO over to the Add-on activation |
configuration_required |
a true or false value. if set to true the user will be immediately redirect over SSO after activation. |
url |
The URL representing the Add-on activation. EY will make a DELETE to this URL if the Add-on is de-activated. |
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:41 GMT
Content-Type: application/json
Authorization: AuthHMAC be21181efd39b23f:4xtxIwocEt5g/MaTT4ne9Nr9gXg=
POST http://mock.service/api/1/account/1/provisioned_services_callback
{
"name": "mock_service_helloworld_production_helloworld",
"url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1",
"messages_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1/messages",
"environment": {
"id": "mock_service_helloworld_production_helloworld",
"name": "mock_service_helloworld_production_helloworld"
},
"app": {
"id": "mock_service_helloworld_production_helloworld",
"name": "mock_service_helloworld_production_helloworld",
"framework_env": "mock_service_helloworld_production_helloworld"
}
}
Content-Type: application/json
200
{
"provisioned_service": {
"vars": {
"some_var": "value",
"other_var": "blah"
},
"configuration_url": "http://mock.service/sso/some_provisioned_service",
"configuration_required": false,
"url": "http://mock.service/api/1/some_provisioned_service"
}
}
To visit the Add-on site, a user will click on a 'Dashbaord' link.
Engine Yard will construct the SSO URL by using the configuration_url provided in rsponse to account creation,
with the addition of query parameters describing additional information about the user.
You may notice that none of the parameters identify the account,
so it's important that you generate a configuration_url that includes the needed identifying information.
A final signature query parameter is used to authenticate the request.
A ruby implementation of HMAC signing urls can be found in the eyapihmac gem.
| Name | Description |
|---|---|
access_level |
collaborator or owner, describes the access this user has on the Engine Yard side and may be used to control access level on the Add-on |
ey_return_to_url |
A URL to send the user back to if you want to provide a "Back to Engine Yard" link |
ey_user_id |
An ID uniquely identifiying the user |
ey_user_name |
The name of the user (not guarateed to be unique, can be changed) |
signature |
The HMAC digest of the full URL without this parameter |
timestamp |
the current time |
GET http://mock.service/sso/account/1?access_level=collaborator&ey_return_to_url=https%3A%2F%2Faddons.engineyard.com%2Faddons%2F1&ey_user_id=f5c35db8-c9f9-6086-26b9-e4262aa22ffc&ey_user_name=Testing+TF×tamp=Thu%2C+06+Mar+2014+00%3A51%3A41+GMT&signature=AuthHMAC+be21181efd39b23f%3APhXnPqANu4Y6aTg%2FNxJ0R%2BbZE1I%3D
Content-Type: text/html;charset=utf-8
200
SSO Hello Service Account <a href='https://addons.engineyard.com/addons/1'>Go Back</a>
SSO may also take place in the context of an activation,
the details are the same as Account Level SSO, only the configuration_url
is pulled form the activation repsonse instead of the account.
A ruby implementation of HMAC signing urls can be found in the eyapihmac gem.
| Name | Description |
|---|---|
access_level |
collaborator or owner, describes the access this user has on the Engine Yard side and may be used to control access level on the Add-on |
ey_return_to_url |
A URL to send the user back to if you want to provide a "Back to Engine Yard" link |
ey_user_id |
An ID uniquely identifiying the user |
ey_user_name |
The name of the user (not guarateed to be unique, can be changed) |
signature |
The HMAC digest of the full URL without this parameter |
timestamp |
the current time |
GET http://mock.service/sso/some_provisioned_service?access_level=collaborator&ey_return_to_url=https%3A%2F%2Faddons.engineyard.com%2Faddons%2F1&ey_user_id=f5c35db8-c9f9-6086-26b9-e4262aa22ffc&ey_user_name=Testing+TF×tamp=Thu%2C+06+Mar+2014+00%3A51%3A41+GMT&signature=AuthHMAC+be21181efd39b23f%3AGLvpf4uwd%2FoNj%2FDMoRwVnk9HDOs%3D
Content-Type: text/html;charset=utf-8
200
SSO Hello Provisioned Service <a href='https://addons.engineyard.com/addons/1'>Go Back</a>
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 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.
| Name | Description |
|---|---|
vars |
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. |
| Name | Description |
|---|---|
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) |
url |
The URL representing this activation in the Engine Yard system |
messages_url |
(Deprecated) provided only for backward-compatability |
environment |
(Deprecated) provided only for backward-compatability |
app |
(Deprecated) provided only for backward-compatability |
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:40 GMT
Content-Type: application/json
Authorization: AuthHMAC be21181efd39b23f:BPGiCsHuUCuFs5SI/9TmNVEgyZE=
PUT https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1
{
"provisioned_service": {
"vars": {
"foo": "bar"
}
}
}
Content-Type: application/json; charset=utf-8
Location: https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1
200
{
"name": "mock_service_helloworld_production_helloworld",
"url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1",
"messages_url": "https://addons.engineyard.com/api/1/partners/1/services/1/service_accounts/1/provisioned_services/1/messages",
"environment": {
"id": "mock_service_helloworld_production_helloworld",
"name": "mock_service_helloworld_production_helloworld"
},
"app": {
"id": "mock_service_helloworld_production_helloworld",
"name": "mock_service_helloworld_production_helloworld",
"framework_env": "mock_service_helloworld_production_helloworld"
}
}
If a user chooses to De-activate you Add-on the Engine Yard UI, this API call will be made.
The url used is the url returned by the original activation response
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:41 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: AuthHMAC be21181efd39b23f:L9Du0sfVGiSvGXO8MQ2LsrQTVW0=
DELETE http://mock.service/api/1/some_provisioned_service
Content-Type: application/json
200
{}
If a user chooses to Cancel their account with your Add-on the Engine Yard UI, this API call will be made.
The url used is the url returned by the original account creation response
Accept: application/json
Date: Thu, 06 Mar 2014 00:51:41 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: AuthHMAC be21181efd39b23f:THiBWgT1sOj5Ki/j0Khw2RfPGvQ=
DELETE http://mock.service/api/1/account/1
Content-Type: application/json
200
{}