Cloud Management API 1.5

Sessions

The sessions resource is in charge of creating API sessions that are bound to a given account. The sequence for login into the API is the following: * Perform a POST request to /api/sessions ('create' action) to my.rightscale.com or to any more specific hosts saved from previous sessions. * If the targeted host is not appropriate for the specific account being accessed it will return a 302 http code with a URL with which the client must retry the same POST request. * If the targeted host is the right one and the login is successful, it will return a 204 http code, along with two cookies that will need to be saved and passed in any subsequent API request. * If there is an authentication or authorization problem with the POST request an error (typically 401 or 422 ) may be returned at any point in the above sequence. * If the session expires, it will return a 403 http code with a "Session cookie is expired or invalid" message.

Note that all API calls irrespective of the resource it is acting on, should pass a header "X_API_VERSION" with the value "1.5".

Actions

index

Returns a list of root resources so an authenticated session can use them as a starting point or a way to know what features are available within its privileges.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -b mycookies -X GET https://my.rightscale.com/api/sessions

URLs
GET /api/session [DEPRECATED]
GET /api/sessions
HTTP response code
200 OK
Content-type
application/vnd.rightscale.session

Required roles

Parameters

name required type values regexp blank? description
view no String default, whoami * no Whoami view provides links to the logged-in principal and the account being accessed

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML
{
  "actions": [

  ],
  "message": "You have successfully logged into the RightScale API.",
  "links": [
    {"rel":"account_groups","href":"/api/account_groups"},
    {"rel":"accounts","href":"/api/accounts"},
    {"rel":"alert_specs","href":"/api/alert_specs"},
    {"rel":"alerts","href":"/api/alerts"},
    {"rel":"audit_entries","href":"/api/audit_entries"},
    {"rel":"backups","href":"/api/backups"},
    {"rel":"child_accounts","href":"/api/child_accounts"},
    {"rel":"cloud_accounts","href":"/api/cloud_accounts"},
    {"rel":"clouds","href":"/api/clouds"},
    {"rel":"cookbooks","href":"/api/cookbooks"},
    {"rel":"credentials","href":"/api/credentials"},
    {"rel":"deployments","href":"/api/deployments"},
    {"rel":"identity_providers","href":"/api/identity_providers"},
    {"rel":"multi_cloud_images","href":"/api/multi_cloud_images"},
    {"rel":"network_gateways","href":"/api/network_gateways"},
    {"rel":"network_option_group_attachments","href":"/api/network_option_group_attachments"},
    {"rel":"network_option_groups","href":"/api/network_option_groups"},
    {"rel":"networks","href":"/api/networks"},
    {"rel":"permissions","href":"/api/permissions"},
    {"rel":"placement_groups","href":"/api/placement_groups"},
    {"rel":"preferences","href":"/api/preferences"},
    {"rel":"publication_lineages","href":"/api/publication_lineages"},
    {"rel":"publications","href":"/api/publications"},
    {"rel":"repositories","href":"/api/repositories"},
    {"rel":"right_scripts","href":"/api/right_scripts"},
    {"rel":"route_tables","href":"/api/route_tables"},
    {"rel":"routes","href":"/api/routes"},
    {"rel":"security_group_rules","href":"/api/security_group_rules"},
    {"rel":"self","href":"/api/session"},
    {"rel":"server_arrays","href":"/api/server_arrays"},
    {"rel":"server_template_multi_cloud_images","href":"/api/server_template_multi_cloud_images"},
    {"rel":"server_templates","href":"/api/server_templates"},
    {"rel":"servers","href":"/api/servers"},
    {"rel":"tags","href":"/api/tags"},
    {"rel":"users","href":"/api/users"}
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<session>
  <actions/>
  <message>You have successfully logged into the RightScale API.</message>
  <links>
    <link rel="account_groups" href="/api/account_groups"/>
    <link rel="accounts" href="/api/accounts"/>
    <link rel="alert_specs" href="/api/alert_specs"/>
    <link rel="alerts" href="/api/alerts"/>
    <link rel="audit_entries" href="/api/audit_entries"/>
    <link rel="backups" href="/api/backups"/>
    <link rel="child_accounts" href="/api/child_accounts"/>
    <link rel="cloud_accounts" href="/api/cloud_accounts"/>
    <link rel="clouds" href="/api/clouds"/>
    <link rel="cookbooks" href="/api/cookbooks"/>
    <link rel="credentials" href="/api/credentials"/>
    <link rel="deployments" href="/api/deployments"/>
    <link rel="identity_providers" href="/api/identity_providers"/>
    <link rel="multi_cloud_images" href="/api/multi_cloud_images"/>
    <link rel="network_gateways" href="/api/network_gateways"/>
    <link rel="network_option_group_attachments" href="/api/network_option_group_attachments"/>
    <link rel="network_option_groups" href="/api/network_option_groups"/>
    <link rel="networks" href="/api/networks"/>
    <link rel="permissions" href="/api/permissions"/>
    <link rel="placement_groups" href="/api/placement_groups"/>
    <link rel="preferences" href="/api/preferences"/>
    <link rel="publication_lineages" href="/api/publication_lineages"/>
    <link rel="publications" href="/api/publications"/>
    <link rel="repositories" href="/api/repositories"/>
    <link rel="right_scripts" href="/api/right_scripts"/>
    <link rel="route_tables" href="/api/route_tables"/>
    <link rel="routes" href="/api/routes"/>
    <link rel="security_group_rules" href="/api/security_group_rules"/>
    <link rel="self" href="/api/session"/>
    <link rel="server_arrays" href="/api/server_arrays"/>
    <link rel="server_template_multi_cloud_images" href="/api/server_template_multi_cloud_images"/>
    <link rel="server_templates" href="/api/server_templates"/>
    <link rel="servers" href="/api/servers"/>
    <link rel="tags" href="/api/tags"/>
    <link rel="users" href="/api/users"/>
  </links>
</session>

Click on a format below to see an example response for the 'whoami' view:

JSON XML
{
  "actions": [

  ],
  "message": "You have successfully logged into the RightScale API.",
  "links": [
    {"rel":"account","href":"/api/accounts/524052047"},
    {"rel":"user","href":"/api/users/524304510"}
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<session>
  <actions/>
  <message>You have successfully logged into the RightScale API.</message>
  <links>
    <link rel="account" href="/api/accounts/524052047"/>
    <link rel="user" href="/api/users/524304510"/>
  </links>
</session>

create

Creates API session scoped to a given account. (API login)

This call requires a form of authentication (user and password), as well as the account for which the session needs to be created. Upon successfully authenticating the credentials, the system will return a 204 code and set of two cookies that will serve as the credentials for the session. Both of these cookies must be passed in any of the subsequent requests for this session. If an 302 redirect code is returned, the client is responsible of re-issuing the POST request against the content of the received Location header, passing the exact same parameters again.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -c mycookies -X POST -d email='email@me.com' -d password='mypassword' -d account_href=/api/accounts/11 https://my.rightscale.com/api/sessions

URLs
POST /api/session [DEPRECATED]
POST /api/sessions
HTTP response code
204 No Content

Parameters

name required type values regexp blank? description
account_href yes String * ^/api/accounts/\d+$ no The account href for which the session needs to be created.
email yes String * * no The email to login with.
password yes String * * no The corresponding password.

accounts

List all the accounts that a user has access to.

This call may be executed outside of an existing session. Doing so requires passing a username and password in the request body. The idea is that it should be possible to list accounts that can be used to create a session.

Upon successfully authenticating the credentials, the system will return a 200 OK code and return the list of accounts. If an 302 redirect code is returned, the client is responsible of re-issuing the GET request against the content of the received Location header, passing the exact same parameters again.

Example Request using Curl (not using an existing session):
curl -i -H X_API_VERSION:1.5 -X GET -d email='email@me.com' -d password='mypassword' https://my.rightscale.com/api/sessions/accounts

Example Request using Curl (using an existing session):
curl -i -H X_API_VERSION:1.5 -X GET -b mycookies https://my.rightscale.com/api/sessions/accounts

URLs
GET /api/session/accounts
GET /api/sessions/accounts
HTTP response code
200 OK
Content-type
application/vnd.rightscale.account;type=collection

Parameters

name required type values regexp blank? description
email no String * * no The email to login with if not using existing session.
password no String * * no The corresponding password.
view no String default, extended * no Extended view shows account permissions and products

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML
[{
  "name": "SPEC_ACCOUNT",
  "created_at": "2017/03/02 17:42:04 +0000",
  "updated_at": "2017/03/02 17:42:04 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/524052047"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ]
},{
  "name": "SPEC_ACCOUNT",
  "created_at": "2017/03/02 17:42:04 +0000",
  "updated_at": "2017/03/02 17:42:04 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/524052047"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ]
}]
<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2017/03/02 17:42:04 +0000</created_at>
    <updated_at>2017/03/02 17:42:04 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/524052047"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
  </account>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2017/03/02 17:42:04 +0000</created_at>
    <updated_at>2017/03/02 17:42:04 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/524052047"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
  </account>
</accounts>

Click on a format below to see an example response for the 'extended' view:

JSON XML
[{
  "name": "SPEC_ACCOUNT",
  "created_at": "2017/03/02 17:42:04 +0000",
  "updated_at": "2017/03/02 17:42:04 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/524052047"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ],
  "products": [

  ],
  "permissions": [

  ]
},{
  "name": "SPEC_ACCOUNT",
  "created_at": "2017/03/02 17:42:04 +0000",
  "updated_at": "2017/03/02 17:42:04 +0000",
  "links": [
    {"rel":"self","href":"/api/accounts/524052047"},
    {"rel":"owner","href":"/api/users/888"},
    {"rel":"cluster","href":"/api/clusters/9"}
  ],
  "products": [

  ],
  "permissions": [

  ]
}]
<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2017/03/02 17:42:04 +0000</created_at>
    <updated_at>2017/03/02 17:42:04 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/524052047"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
    <products/>
    <permissions/>
  </account>
  <account>
    <name>SPEC_ACCOUNT</name>
    <created_at>2017/03/02 17:42:04 +0000</created_at>
    <updated_at>2017/03/02 17:42:04 +0000</updated_at>
    <links>
      <link rel="self" href="/api/accounts/524052047"/>
      <link rel="owner" href="/api/users/888"/>
      <link rel="cluster" href="/api/clusters/9"/>
    </links>
    <products/>
    <permissions/>
  </account>
</accounts>

create_instance_session

Creates API session scoped to a given account and instance.

This call requires a form of authentication (token), as well as the account for which the session needs to be created. Upon successfully authenticating the credentials, the system will return a 204 code and set of two cookies that will serve as the credentials for the session. Both of these cookies must be passed in any of the subsequent requests for this session. If an 302 redirect code is returned, the client is responsible of re-issuing the POST request against the content of the received Location header, passing the exact same parameters again.

Users can find their account ID and instance\_token from their instance's user_data:
account ID regex: /RS_API_TOKEN=(\d+):/
instance_token regex: /RS_API_TOKEN=(?:\d+):(\w+)&/

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -c mycookies -X POST -d instance_token='randomtoken' -d account_href=/api/accounts/11 https://my.rightscale.com/api/sessions/instance

URLs
POST /api/session/instance
POST /api/sessions/instance
HTTP response code
204 No Content

Parameters

name required type values regexp blank? description
account_href yes String * ^/api/accounts/\d+$ no The account href for which the session needs to be created.
instance_token yes String * * no The instance token to login with.

index_instance_session

Shows the full attributes of the instance (that has the token used to log-in). This call can be used by an instance to get it's own details.

Example Request using Curl:
curl -i -H X_API_VERSION:1.5 -b mycookies -X GET https://my.rightscale.com/api/sessions/instance

URLs
GET /api/session/instance
GET /api/sessions/instance
HTTP response code
200 OK
Content-type
application/vnd.rightscale.instance

Required roles

Example Responses

Click on a format below to see an example response:

JSON XML
{
  "name": "NAME_3471584400",
  "created_at": "2017/03/02 17:42:05 +0000",
  "updated_at": "2017/03/02 17:42:05 +0000",
  "resource_uid": "RESOURCE_729005368",
  "links": [
    {"rel":"self","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"deployment","href":"/api/deployments/2"},
    {"rel":"server_template","href":"/api/server_templates/1"},
    {"rel":"multi_cloud_image","href":"/api/multi_cloud_images/1","inherited_source":"server_template"},
    {"rel":"parent","href":"/api/servers/1"},
    {"rel":"volume_attachments","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND/volume_attachments"},
    {"rel":"inputs","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND/inputs"},
    {"rel":"monitoring_metrics","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND/monitoring_metrics"},
    {"rel":"alerts","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND/alerts"},
    {"rel":"alert_specs","href":"/api/clouds/888/instances/RESOURCE_729005368;RAND/alert_specs"}
  ],
  "cloud_specific_attributes": {
  },
  "associate_public_ip_address": true,
  "actions": [
    {
      "rel": "terminate"
    },
    {
      "rel": "reboot"
    },
    {
      "rel": "run_executable"
    },
    {
      "rel": "lock"
    },
    {
      "rel": "unlock"
    }
  ],
  "public_ip_addresses": [
    "205.171.115.19"
  ],
  "private_ip_addresses": [
    "3.3.6.9"
  ],
  "pricing_type": "fixed",
  "locked": false,
  "state": "operational"
}
<?xml version="1.0" encoding="UTF-8"?>
<instance>
  <name>NAME_3471584400</name>
  <created_at>2017/03/02 17:42:05 +0000</created_at>
  <updated_at>2017/03/02 17:42:05 +0000</updated_at>
  <resource_uid>RESOURCE_729005368</resource_uid>
  <links>
    <link rel="self" href="/api/clouds/888/instances/RESOURCE_729005368;RAND"/>
    <link rel="cloud" href="/api/clouds/888"/>
    <link rel="deployment" href="/api/deployments/2"/>
    <link rel="server_template" href="/api/server_templates/1"/>
    <link rel="multi_cloud_image" href="/api/multi_cloud_images/1" inherited_source="server_template"/>
    <link rel="parent" href="/api/servers/1"/>
    <link rel="volume_attachments" href="/api/clouds/888/instances/RESOURCE_729005368;RAND/volume_attachments"/>
    <link rel="inputs" href="/api/clouds/888/instances/RESOURCE_729005368;RAND/inputs"/>
    <link rel="monitoring_metrics" href="/api/clouds/888/instances/RESOURCE_729005368;RAND/monitoring_metrics"/>
    <link rel="alerts" href="/api/clouds/888/instances/RESOURCE_729005368;RAND/alerts"/>
    <link rel="alert_specs" href="/api/clouds/888/instances/RESOURCE_729005368;RAND/alert_specs"/>
  </links>
  <cloud_specific_attributes/>
  <associate_public_ip_address>true</associate_public_ip_address>
  <actions>
    <action rel="terminate"/>
    <action rel="reboot"/>
    <action rel="run_executable"/>
    <action rel="lock"/>
    <action rel="unlock"/>
  </actions>
  <public_ip_addresses>
    <public_ip_address>205.171.115.19</public_ip_address>
  </public_ip_addresses>
  <private_ip_addresses>
    <private_ip_address>3.3.6.9</private_ip_address>
  </private_ip_addresses>
  <pricing_type>fixed</pricing_type>
  <locked>false</locked>
  <state>operational</state>
</instance>