Sonnet API Advanced

List Services

List the Add-ons you've registered

Response Parameters

Name	Description
`name`	Name of the Add-on
`label`	label for the Add-on
`home_url`	(deprected) ignore
`service_accounts_url`	URL to which EY will POST for account creation
`service_accounts_listing_url`	the URL to see a listing of accounts using the Add-on (GET to it)
`vars`	(deprected) ignore
`description_html`	(deprected) ignore
`terms_and_conditions_url`	(deprected) ignore
`description`	(deprected) ignore
`url`	the URL for this Add-on ('GET', 'PUT' and 'DELETE' to this url to get info, update, or destroy the Add-on)

Example Request

Headers

Accept: application/json
Date: Wed, 18 Dec 2013 23:32:32 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: AuthHMAC f1f2156aa37003e8:k2dETO+J3bP6Z30JGWTUS9Siz1w=

Route

GET https://addons.engineyard.com/api/1/partners/3/services

Body

Example Response

Headers

Content-Type: application/json; charset=utf-8

Status

Body

[
  {
    "service": {
      "name": "Mock Service 1",
      "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/3/services/3",
      "service_accounts_listing_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts"
    },
    "url": "https://addons.engineyard.com/api/1/partners/3/services/3"
  }
]

Add-ons using the Sonnet API are not automatically invoiced by Engine Yard. Instead it is the Partner's responsibility to send discrete billing events (generally once a month). Engine Yard customers are billing once a month, for charges accumulated in the previous month. Accordingly, there is a 24 hour cutoff period for submitting invoices after the month ends (GMT+8). Submitted invoices will be assigned to the nearest open billing cycle, so if you miss the cutoff the invoice will be charged the next month.

If an account cancels, you have 24 hours to submit invoices to that account, after that invoices will be rejected.

Request Parameters

Name	Description
`line_item_description`	Description of the charge, will appear on customer bill
`total_amount_cents`	Amount to charge in USD times 100 (total amount in cents)
`unique_id`	(optional) Not show to the customer, but usefull for reconciliation. It's best to use some internal ID that uniquely identifies this billing event. If a duplicate ID is sent (within the scope of a customer) the invoice will be rejected, thus this field is useful to avoid accidental overcharges.

Response Parameters

Name	Description
`account_id`	The ID of the account being invoiced, as returned in Account creation
`invoice_date`	The date of the invoice (will be used to determine in which billing cycle to charge the customer)
`line_item_description`	As sent in the request
`total_amount_cents`	As sent in the request
`unique_id`	As sent in the request
`status`	"pending" or "locked" to indicate whether the invoice can be updated (or too late)
`updated_at`	Last time this invoice was updated
`url`	URL used to fetch or update this invoice

Example Request

Headers

Accept: application/json
Date: Wed, 18 Dec 2013 23:32:32 GMT
Content-Type: application/json
Authorization: AuthHMAC f1f2156aa37003e8:Gq8jTYvSd87piCc9+RaUser4UpQ=

Route

POST https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices

Body

{
  "invoice": {
    "total_amount_cents": 1299,
    "line_item_description": "Mock Service 1 from 01 December 2013 to 31 December 2013",
    "unique_id": "0139af63928c46689a61d39ddcf95666"
  }
}

Example Response

Headers

Content-Type: application/json; charset=utf-8
Location: https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices/2

Status

Body

{
  "invoice": {
    "line_item_description": "Mock Service 1 from 01 December 2013 to 31 December 2013",
    "total_amount_cents": 1299,
    "unique_id": "0139af63928c46689a61d39ddcf95666",
    "invoice_date": "2013-12-18T23:32:32.480Z",
    "updated_at": "2013-12-18T23:32:32.480Z",
    "status": "pending",
    "account_id": 3,
    "url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices/2"
  },
  "url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices/2"
}

Account Info (e-mails)

A GET request to the url representing an account will provide you with additional information on that account, including the e-mail addresses of the account owners.

This url is sent as part of the Account creation API

Response Parameters

Name	Description
`configuration_required`	The value the Add-on provided in response to account creation. displayed here so you can check that you've updated it successfully.
`configuration_url`	The url to the partner Add-on for SSO at the account level (will be signed before visited)
`id`	Id that uniquely identifies the account being created
`invoices_url`	The URL to POST invoices to charge this user for services
`messages_url`	(Deprecated) provided only for backward-compatability
`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)
`owner_email`	The e-mail address of the first owner of the account (subject to change, please re-check this API every time you need to send an e-mail)
`owner_emails`	The slightly more accurate version of owner_email gives you an array of e-mails in case the account has more than 1 owner (also subject to change)
`provisioned_services_url`	The URL representing the set of activations for this account
`updateable_urls`	The set of URLs stored in EY systems that point to the Add-on system for this account, you may udpate these (as well as `configuration_required` and `configuration_url`) with a PUT to `url`
`url`	The URL representing the account being created by the API call in the EY system

Example Request

Headers

Accept: application/json
Date: Wed, 18 Dec 2013 23:32:32 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: AuthHMAC f1f2156aa37003e8:yh8Km0Aeki4zKLlLfDrBbK4L7fk=

Route

GET https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3

Body

Example Response

Headers

Content-Type: application/json; charset=utf-8
Location: https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3

Status

Body

{
  "configuration_required": false,
  "id": 3,
  "invoices_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices",
  "messages_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/messages",
  "name": "testing-tf",
  "owner_email": "tftesting@engineyard.com",
  "owner_emails": [
    "tftesting@engineyard.com"
  ],
  "provisioned_services_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/provisioned_services",
  "updateable_urls": {
    "configuration_url": "http://mock.service/sso/account/3",
    "provisioned_services_url": "http://mock.service/api/1/account/3/provisioned_services_callback",
    "url": "http://mock.service/api/1/account/3"
  },
  "url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3"
}

Account Info (listing)

A GET request to the service_accounts_listing_url for you Add-on will provide you with a full list of active account.

This service_accounts_listing_url is available as part of the List Services API

Response Parameters

Name	Description
`id`	Id that uniquely identifies the account being created
`invoices_url`	The URL to POST invoices to charge this account for services
`messages_url`	(Deprecated) provided only for backward-compatability
`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)
`provisioned_services_url`	The URL representing the set of activations for this account
`url`	The URL representing the account (GET to this url for more info)

Example Request

Headers

Accept: application/json
Date: Wed, 18 Dec 2013 23:32:32 GMT
Content-Type: application/x-www-form-urlencoded
Authorization: AuthHMAC f1f2156aa37003e8:xFgnkeheaadR4ZBFeL0MZmGE7PI=

Route

GET https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts

Body

Example Response

Headers

Content-Type: application/json; charset=utf-8

Status

Body

[
  {
    "id": 3,
    "invoices_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/invoices",
    "messages_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/messages",
    "name": "testing-tf",
    "provisioned_services_url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3/provisioned_services",
    "url": "https://addons.engineyard.com/api/1/partners/3/services/3/service_accounts/3"
  }
]

Sonnet API Advanced

List Services

Response Parameters

Example Request

Headers

Route

Body

Example Response

Headers

Status

Body

Invoicing

Request Parameters

Response Parameters

Example Request

Headers

Route

Body

Example Response

Headers

Status

Body

Account Info (e-mails)

Response Parameters

Example Request

Headers

Route

Body

Example Response

Headers

Status

Body

Account Info (listing)

Response Parameters

Example Request

Headers

Route

Body

Example Response

Headers

Status

Body