API Guide¶
This guide will cover the basics of a pilot request. If you are in need of more in depth customization, see the Custom API Guide documentation.
Note that any parameters sent to Pilot for the sake of customization will be stored and accessible in the browser–do not place sensitive data in query parameters or POST payloads.
Environments¶
Production:
https://prod.pilot.api.rackspacecloud.com
Preprod:
https://preprod.pilot.api.rackspacecloud.com
Staging:
https://staging.pilot.api.rackspacecloud.com/
Request API Contract¶
Path¶
You should insert the return value of this into your navigation element.
| VERB | PATH | DESCRIPTION |
|---|---|---|
| GET | /v1/cloud/<tenant>/navigation | Request the header for Rackspace Cloud properties. |
Attributes¶
| NAME | LOCATION | REQUIRED | DESCRIPTION |
|---|---|---|---|
| tenant | URL | Yes | The tenant ID of the user for whom a header is being generated. |
| active | Query String | No | The navigation item to highlight in the returned response. |
| mycloud | Query String | No | The base URL for MyCloud links. (Defaults to “https://mycloud.rackspace.com”). |
| cdn | Query String | No | The base URL for CDN links. (Defaults to “https://mycdn.rackspace.com”). |
| backup | Query String | No | The base URL for Backup links. (Defaults to “https://<MyCloud URL>/ck/sso/backup?redirect=”). |
Headers¶
| NAME | REQUIRED | DESCRIPTION |
|---|---|---|
| X-Auth-Token | Yes | The authentication token provided by identity api for the user. |
Sample Request¶
curl --request GET \
--header "X-Auth-Token: $TOKEN" \
"https://prod.pilot.api.rackspacecloud.com/v1/cloud/$TENANT/navigation"
Default Header Contract¶
The configuration for Pilot defines a maximum response time of 10 seconds. This 10 seconds is designed to give the APIs Pilot talks to (Identity and Support Service) enough time to respond. At the end of 10 seconds, Pilot will respond to the header generation request with an error code.
In the event of this sort of Pilot slowness, non-200 response, or, in the worst case, downtime, consumers of Pilot should fetch a user-generic “default” Pilot header. This header is pre-generated and stored in Rackspace Cloud Files.
| VERB | PATH | DESCRIPTION |
|---|---|---|
| GET | https://2bb412f1e613f0876bcd-c2711431ca6ffe5afee18d654580dd9b.ssl.cf1.rackcdn.com | Request the header for Rackspace Cloud properties. |
Note: We used to have a custom domain that pointed to the default header. However this domain was http only, and because of Cloud Files restrictions, it could not be https-enabled. That custom domain will continue to be reachable (but no longer documented), so we don’t break existing control panels that have no developer resources. However all control panels with developers should migrate to the https domain above.
Javascript API Contract¶
Pilot exposes a JavaScript API that allows consumers of the Pilot API to highlight the active navigation dropdown and corresponding navigation link to inform the user of their current location within the Rackspace suite of control panels.
| NAMESPACE | METHOD | ARGUMENTS |
|---|---|---|
| pilot | setActive | String activeMainNavItem, String activeSubnavItem |
| pilot | setEyebrowActive | String activeMainNavItem |
Example:
/*
* Changes the active highlighted items in the Pilot primary/application navigation
* @param {string} activeMainNavItem - The value in the attribute 'data-nav' of the navigation element to highlight
* @param {string} activeSubNavItem - The value in the attribute 'data-subnav' of the dropdown element in the dropdown specified by the first element
*/
pilot.setActive('servers', 'auto-scale');
/*
* Changes the active highlighted item in the Pilot eyebrow
* @param {string} activeMainNavItem - The primary/application navigation element `[data-nav]` corresponding to attribute data-nav
*/
pilot.setEyebrowActive('user');