Back to top

API v2.0 Authentication Overview

Summary

L'authentification pour l'API v2 se fait à l'aide des mêmes identifiants que ceux utilisés pour accéder au portail de commande de l’infonuagique CenturyLink. The username and password are provided to the API and in return, the user gets back a credentials object that contains a valid bearer token. This token -- which can be reused for up to 2 weeks -- must be provided on each subsequent API request.

Walkthrough

.NET Framework Example

Below is a brief demonstration of using the .NET framework to retrieve a valid token from the API authentication service.

  1. Reference the assemblies needed to make HTTP requests.
using System.Net.Http;
using System.Net.Http.Headers;
  1. Create an instance of the HttpClient object.
HttpClient authClient = new HttpClient();
  1. Add an Accept header to indicate that returning JSON as a response is ok.
authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
  1. Create an HttpContent object to hold the JSON payload ({"username": "[username]", "password": "[password]"}) sent to the API. Also, note that the content type application/json is set.
HttpContent content =
   new StringContent("{ \"username\":\"[username]\", \"password\":\"[password]\" }", null, "application/json");
  1. Invoke the API and send the HTTP content using a POST command.
HttpResponseMessage message =
    await authClient.PostAsync("https://api.ctl.io/v2/authentication/login", content);
  1. Load the response into a string for parsing.
string responseString = await message.Content.ReadAsStringAsync();

If valid credentials are provided, an HTTP 200 status is returned along with the following JSON payload:

  {
     "userName":"user@company.com",
     "accountAlias":"RLS1",
     "locationAlias":"WA1",
     "roles":[
        "ServerAdmin",
        "AccountAdmin"
     ],
     "bearerToken":"[LONG TOKEN VALUE]"
  }

Ces résultats montrent le compte parent de l'utilisateur, le centre informatique par défaut et les rôles de plateforme attribués. The bearerToken is the value that must be added to the HTTP Authorization header when calling any other API service. Ce jeton identifie l'utilisateur et permet de connaître les autorisations dont il dispose dans l'API.

Si vous entrez des renseignements d'identification incorrects, vous obtiendrez un message d'erreur HTTP 400 (Bad Request), ainsi que la réponse suivante :

{"message":"We didn't recognize the username or password you entered. Veuillez réessayer."}
  1. Submit a request: the following .NET code demonstrates how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".
  HttpClient authClient = new HttpClient();

  authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

  // Add bearer token to the header
  authClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Bearer [LONG TOKEN VALUE]");

  HttpResponseMessage message = await authClient.GetAsync("https://api.ctl.io/v2/datacenters/DEMO/CA1");

  string responseString = await message.Content.ReadAsStringAsync();

PowerShell Example

Below is a brief demonstration of how PowerShell can be used to retrieve a valid token from the API authentication service.

  1. Log into the API.
$Body = @{ 
Username = 'CONTROL_USERNAME' 
Password = 'CONTROL_PASSWORD' 
}
  1. Log in to the Platform and get back a bearerToken.
$LogonUri = 'https://api.ctl.io/v2/authentication/login' 
$LogonResponse = Invoke-RestMethod -Method Post -Uri $LogonUri -Body $Body -SessionVariable WebSession
  1. Pull the BearerToken out of the response and format it correctly. Note that a prefix of "Bearer " is required.
$Bearer = 'Bearer ' + $LogonResponse.bearerToken
  1. Add Accept and Authorization headers to the session variable to be used on future requests.
$WebSession.Headers.Add('Accept', 'application/json') 
$WebSession.Headers.Add('Authorization', $Bearer)

You can now use the session variable for authenticating further API calls. Example:

Here's an example of pulling server credentials:

  $AccountAlias = 'ACCOUNT_ALIAS' 
  $ServerName = 'SERVER_NAME' 
  $ServercredsURL = "https://api.ctl.io/v2/servers/$AccountAlias/$ServerName/credentials" 
  $ServerCreds = Invoke-RestMethod -Uri $servercredsURL -WebSession $WebSession 
  $ServerCreds

Raw HTTP Example

L'exemple ci-dessous illustre des messages de requête et de réponses HTTP bruts lors de la récupération d'un jeton valide depuis le service d'authentification de l'API.

Requête

POST https://api.ctl.io/v2/authentication/login HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 54

{
  "username": "[username]",
  "password": "[password]"
}

Réponse

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:23:45 GMT
Content-Length: 149

{
  "userName": "user@company.com",
  "accountAlias": "RLS1",
  "locationAlias": "WA1",
  "roles": [
    "ServerAdmin",
    "AccountAdmin"
  ],
  "bearerToken": "[LONG TOKEN VALUE]"
}

Ces résultats montrent le compte parent de l'utilisateur, le centre informatique par défaut et les rôles de plateforme attribués. Le jeton d'authentification (bearerToken) est la valeur qui doit être ajoutée à l'en-tête HTTP Authorization lorsque tout autre service API est contacté. Ce jeton identifie l'utilisateur et permet de connaître les autorisations dont il dispose dans l'API.

Si vous entrez des renseignements d'identification incorrects, vous obtiendrez un message d'erreur HTTP 400 (Bad Request), ainsi que la réponse suivante :

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:26:45 GMT
Content-Length: 89

{"message":"We didn't recognize the username or password you entered. Veuillez réessayer."}

The following raw HTTP request message shows how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".

GET https://api.ctl.io/v2/datacenters/RLS1/WA1 HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 0
Authorization: Bearer [LONG TOKEN VALUE]

API v2.0 Links Framework

Aperçu

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. Many of the JSON response entities include a links attribute which contains an array of link entities for resources that are related the object that was just acted upon.

This link model helps with both discoverability as well as use-case scalability. In addition, it provides a mechanism for exposing only those endpoints that are available to a user based on their role. In other words, a user will only see links and associated actions that they have access to. Each link entity contains a URL in the href attribute so the API user may simply follow the link to perform a followup action.

Link Entity

Each link entity defines the following properties. For more details about each specific link type, see the Link Definitions for each resource type.

Name Type Description Req.
rel chaîne The link type, as described in the table below. Oui
href chaîne Address of the resource. Oui
id chaîne Unique ID of the resource. Non
nom chaîne Friendly name of the resource. Non
verbs array Valid HTTP verbs that can act on this resource. If none are explicitly listed, GET is assumed to be the only one. Non

API v2.0 Overview

The CenturyLink Cloud has a new, improved API for performing the same actions programmatically as you can with the Control Portal. The API is RESTful and works with JSON messages over HTTP. It relies on the standard HTTP verbs including GET, POST, PUT, DELETE, and PATCH.

The URL format of the service is: https://api.ctl.io/v2/{resource}/{account alias}. As an example, to retrieve the top level Group for a given data center, you would issue a GET request to https://api.ctl.io/v2/datacenters/ALIAS/WA1. The HTTP request must include Content-Type and Accepts headers set to application/json.

Authentification

Service authentication is done via bearer tokens and is outlined in the Authentication Overview and also the Login API description.

Links Framework

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. See more information in our overview of the Links Framework.

HTTP Response Codes

The service responds to requests using standard HTTP codes, and if applicable, a JSON payload.

HTTP Code Description
200 OK. Sent when requests are immediately successful and did NOT create a new URL-addressable resource.
201 CREATED. Sent when requests are immediately successful and DID create a new URL-addressable resource.
202 ACCEPTED. Sent when requests result in a scheduled activity. Response body will include a URL for them to get the status of the activity.
204 NO CONTENT. Sent when requests are immediately successful but return no additional information about the resource.
400 BAD REQUEST. Sent when something is wrong with the query string or message body.
401 UNAUTHORIZED. Sent when a bearer token is not provided.
403 FORBIDDEN. Sent if the request violates the security demands of the service.
404 NOT FOUND. Sent if the URL points to a non-existent resource.
500 INTERNAL SERVER ERROR. Sent if the service experiences an error through no fault of the user.

Create Alert Policy

Creates an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new alert policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/alertPolicies/ALIAS

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the alert policy. Oui
actions array The actions to perform when the alert is triggered. Oui
triggers array The definition of the triggers that fire the alert. Oui

Actions Entity

Name Type Description
action chaîne The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric chaîne The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration chaîne The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold nombre The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 80%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":80.0
    }
  ]
}

Réponse

Entity Definition

Name Type Description
id chaîne ID of the alert policy.
nom chaîne Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 80%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "user@company.com"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 80.0
    }
  ]
}

Delete Alert Policy

Deletes a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific alert policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the alert policy being queried. Oui

Réponse

The response will not contain JSON content, but should return a standard HTTP 200 OK response upon deletion of the policy.

Get Alert Policies

Gets a list of alert policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of alert policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that alert policy using the API.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Réponse

The response will be an items objects referencing an array containing one entity for each alert policy in the given account.

Entity Definition

Name Type Description
id chaîne ID of the alert policy.
nom chaîne Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type Description
action chaîne The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric chaîne The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration chaîne The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold nombre The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "items":[
    {
      "id":"999de90f25ab4308a6c346cd03602fef",
      "name":"Memory Above 90%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "user@company.com"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"memory",
          "duration":"00:10:00",
          "threshold":90.0
        }
      ]
    },
    {
      "id":"175c3b5743d64cea952a5cca03bdb2da",
      "name":"CPU Above 75%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "user@company.com"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/175c3b5743d64cea952a5cca03bdb2da",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"cpu",
          "duration":"00:05:00",
          "threshold":75.0
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Alert Policy

Gets a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific alert policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the alert policy being queried. Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the alert policy.
nom chaîne Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type Description
action chaîne The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric chaîne The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration chaîne The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold nombre The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "id":"999de90f25ab4308a6c346cd03602fef",
  "name":"Memory Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers":[
    {
      "metric":"memory",
      "duration":"00:10:00",
      "threshold":90.0
    }
  ]
}

Update Alert Policy

Updates the name of an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing alert policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the alert policy being updated. Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the alert policy. Oui
actions array The actions to perform when the alert is triggered. Oui
triggers array The definition of the triggers that fire the alert. Oui

Actions Entity

Name Type Description
action chaîne The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric chaîne The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration chaîne The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold nombre The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":90.0
    }
  ]
}

Réponse

Entity Definition

Name Type Description
id chaîne ID of the alert policy.
nom chaîne Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 90%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "user@company.com"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 90.0
    }
  ]
}

Create Anti-Affinity Policy

Creates an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new anti-affinity policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the anti-affinity policy. Oui
emplacement chaîne Data center location of the anti-affinity policy. Oui

Examples

JSON

{
  "name":"New Anti-Affinity Policy",
  "location":"VA1"
}

Réponse

Entity Definition

Name Type Description
id chaîne ID of the anti-affinity policy.
nom chaîne Name of the anti-affinity policy.
emplacement chaîne Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{

  "id":"80a7bf90b459454b859399aef54f4173",
  "name":"New Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b459454b859399aef54f4173"
    }
  ]
}

Delete Anti-Affinity Policy

Deletes a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific anti-affinity policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the anti-affinity policy being queried. Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy.

Get Anti-Affinity Policies

Gets a list of anti-affinity policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of anti-affinity policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that anti-affinity policy using the API.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Réponse

The response will be an items objects referencing an array containing one entity for each anti-affinity policy in the given account.

Entity Definition

Name Type Description
id chaîne ID of the anti-affinity policy.
nom chaîne Name of the anti-affinity policy.
emplacement chaîne Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "items":[
    {
      "id":"80a7bf90b199454b859399bff54f4173",
      "name":"My Anti-Affinity Policy",
      "location":"VA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        },
        {
          "rel":"server",
          "href":"/v2/servers/alias/va1aliashypsc01",
          "id":"va1aliashypsc01",
          "name":"VA1ALIASHYPSC01"
        }
      ]
    },
    {
      "id":"ca8b07035cf844f3b4f953074c2630eb",
      "name":"My Other Anti-Affinity Policy",
      "location":"WA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/ca8b07035cf844f3b4f953074c2630eb",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Anti-Affinity Policy

Gets a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific anti-affinity policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the anti-affinity policy being queried. Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the anti-affinity policy.
nom chaîne Name of the anti-affinity policy.
emplacement chaîne Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Update Anti-Affinity Policy

Updates the name of an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing anti-affinity policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
PolicyId chaîne ID of the anti-affinity policy being updated. Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the anti-affinity policy. Oui

Examples

JSON

{
  "name":"Changed Name of Anti-Affinity Policy",
}

Réponse

Entity Definition

Name Type Description
id chaîne ID of the anti-affinity policy.
nom chaîne New name of the anti-affinity policy.
emplacement chaîne Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173"
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Acquires an authentication token used for subsequent queries to the API.

When to Use It

Use this API operation before you call any other API operation. It shows a user's roles, primary data center, and a valid bearer token.

URL

Structure

POST https://api.ctl.io/v2/authentication/login

Requête

Content Properties

Name Type Description Req.
username chaîne Control Portal user name value Oui
password chaîne Control Portal password value. Oui

Examples

JSON

{
   "username":"demouser1",
   "password":"mypassword"
}

Réponse

Entity Definition

Name Type Description
userName chaîne Control Portal user name value
accountAlias chaîne Account that contains this user record
locationAlias chaîne Default data center of the user
roles array Permission roles associated with this user
bearerToken chaîne Security token for this user that is included in the Authorization header for all other API requests as "Bearer [LONG TOKEN VALUE]".

Examples

JSON

{
    "userName": "user@email.com",
    "accountAlias": "ALIAS",
    "locationAlias": "DC1",
    "roles": [
        "AccountAdmin",
        "ServerAdmin"
    ],
    "bearerToken": "[LONG TOKEN VALUE]"
}

Get Vertical Autoscale Policies

Gets a list of vertical autoscale policies for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of vertical autoscale policies for a given account, and to see what servers are associated with these policies. You can also use the IDs provided in this list to add a server to that autoscale policy using Set Vertical Autoscale Policy On Server API method.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui

Réponse

The response will be an array containing one entity for each autoscale policy in the given account.

Entity Definition

Name Type Description
id chaîne ID of the vertical autoscale policy
nom chaîne Name of the vertical autoscale policy
resourceType chaîne The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs; this is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type Description
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type Description
start chaîne Start time of window in UTC
end chaîne End time of window in UTC

Examples

JSON

      {
        "id": "3b6f26003c224596bc7e748a0adc97d5",
        "name": "Production Database Scale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 6,
          "min": 2
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "02:00",
          "end": "04:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/3b6f26003c224596bc7e748a0adc97d5"
          }
        ]
      },
      {
        "id": "23a68b22e35b4983abd1051fae10ee7b",
        "name": "Another CPU Autoscale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 4,
          "min": 1
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "00:00",
          "end": "23:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/23a68b22e35b4983abd1051fae10ee7b"
          }
        ]
      }

Get Vertical Autoscale Policy

Gets a given vertical autoscale policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a vertical autoscale policy for a given account.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS/80a7bf90b199464b859399bff54f4173

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
policyId chaîne ID of the autoscale policy being queried Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the vertical autoscale policy
nom chaîne Name of the vertical autoscale policy
resourceType chaîne The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs. This is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type Description
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type Description
start chaîne Start time of window in UTC
end chaîne End time of window in UTC

Examples

JSON

    {
      "id": "9d14822c1e8541cea11703cf2b078c9d",
      "name": "Production Database Scale Policy",
      "resourceType": "cpu",
      "thresholdPeriodMinutes": 5,
      "scaleUpIncrement": 1,
      "range": {
        "max": 6,
        "min": 2
      },
      "scaleUpThreshold": 85,
      "scaleDownThreshold": 15,
      "scaleDownWindow": {
        "start": "02:00",
        "end": "04:00"
      },
      "links": [
        {
          "rel": "self",
          "href": "/v2/autoscalePolicies/ALIAS/9d14822c1e8541cea11703cf2b078c9d"
        }
      ]
    }

Remove Vertical Autoscale Policy from Server

Removes the autoscale policy from a given server, if the policy has first been applied to the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to remove the autoscale policy from a server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server. Retrieved from query to containing a group, or by looking at the URL when viewing a server in the Control Portal. Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy from the server.

Set Vertical Autoscale Policy on Server

Sets the autoscale policy for a specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set the autoscale policy of a server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

PUT https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
id chaîne The unique identifier of the autoscale policy to apply to the server. Can be retrieved by calling Get Vertical Autoscale Policies. Oui

Examples

JSON

    {
      "id": "3440b69f139c435b8f9462b0661014fc"
    }

Réponse

Entity Definition

Name Type Value Description
id chaîne ID of the autoscale policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON


  {
    "id": "3440b69f139c435b8f9462b0661014fc",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

View Vertical Autoscale Policy on Server

Gets the autoscale policy of a given server, if a policy has been applied on the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the autoscale policy of a given server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Réponse

Entity Definition

Name Type Value Description
id chaîne ID of the autoscale policy
links array Collection of entity links that point to resources related to this policy

Examples

JSON

  {
    "id": "6c8d7b5349054fe6a532539ff066b53b",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

Get Invoice Data for an Account Alias

Gets a list of invoicing data for a given account alias for a given month. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

NOTE: THE DATA RETURNED IN THIS API ARE USAGE ESTIMATES ONLY, AND DOES NOT REPRESENT AN ACTUAL BILL.

When to Use It

Use this API operation when you want to get invoicing data for a given account for a given month.

URL

Structure

GET https://api.ctl.io/v2/invoice/{accountAlias}/{year}/{month}

Example

GET https://api.ctl.io/v2/invoice/ALIAS/2015/7/?pricingAccount=PALIAS

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
year integer Year of usage, in YYYY format. Oui
month integer Monthly period of usage, in M format. Oui
pricingAccountAlias chaîne Short code of the account that sends the invoice for the accountAlias Non

Réponse

The response includes a JSON object containing an array with invoicing data.

Entity Definition

Name Type Description
id chaîne ID of the account alias being queried
terms chaîne payment terms associated with the account
companyName chaîne Description of the account name
accountAlias chaîne Short code for a particular account
pricingAccountAlias chaîne Short code for a particular account that receives the bill for the accountAlias usage
parentAccountAlias chaîne Short code for the parent account alias associated with the account alias being queried
address1 chaîne First line of the address associated with accountAlias
address2 chaîne Second line of the address associated with accountAlias
city chaîne City associated with the accountAlias
stateProvince chaîne State or province associated with the accountAlias
postalCode chaîne Postal code associated with the accountAlias
billingContactEmail chaîne Billing email address associated with the accountAlias
invoiceCCEmail chaîne Additional billing email address associated with the accountAlias
totalAmount decimal Invoice amount in dollars
invoiceDate chaîne Date the invoice is finalized
poNumber chaîne Purchase Order associated with the Invoice
lineItems array Usage details of a resource or collection of similar resources

Line Items Definition

Name Type Description
quantity integer Quantity of the line item
description chaîne Text description of the line item
unitCost decimal Unit cost of the line item
itemTotal decimal Total cost of the line item
serviceLocation chaîne Location of the line item
itemDetails complex Details about the line item

Examples

JSON

{
    "id": "ALIAS69849A66",
    "terms": "Net 15",
    "companyName": "CTL Cloud Solutions",
    "accountAlias": "ALIAS",
    "pricingAccountAlias": "ALIAS",
    "parentAccountAlias": "PALIAS",
    "address1": "1100 112th Ave NE",
    "address2": "Suite 400",
    "city": "Bellevue",
    "stateProvince": "WA",
    "postalCode": "98004",
    "billingContactEmail": "billing@domain.com",
    "invoiceCCEmail": "",
    "totalAmount": 0,
    "invoiceDate": "2015-08-01T00:00:00Z",
    "poNumber": "",
    "lineItems": [
        {
            "quantity": 1,
            "description": "Server Group: DEMO - VA1",
            "unitCost": 153.93,
            "itemTotal": 153.93,
            "serviceLocation": "VA1",
            "itemDetails": [
                {
                    "description": "VA1ALIASJMB01",
                    "cost": 153.93
                }
            ]
        },
        {
            "quantity": 1,
            "description": "Shared Load Balancer - CA1",
            "unitCost": 29.76,
            "itemTotal": 29.76,
            "serviceLocation": "CA1",
            "itemDetails": []
        },
        {
            "quantity": 1,
            "description": "Additional Networks - GB3",
            "unitCost": 45,
            "itemTotal": 45,
            "serviceLocation": "GB3",
            "itemDetails": []
        },
    ]
}

Get Custom Fields

Retrieves the custom fields defined for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to find out the details of what custom fields are defined for an account.

URL

Structure

GET https://api.ctl.io/v2/accounts/{accountAlias}/customFields

Example

GET https://api.ctl.io/v2/accounts/ACCT/customFields

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Réponse

The response will be an array containing one entity for each custom field defined in the given account.

Entity Definition

Name Type Description
id chaîne Unique identifier of the custom field.
nom chaîne Friendly name of the custom field as it appears in the UI.
isRequired boolean Boolean value representing whether or not a value is required for this custom field.
type chaîne The type of custom field defined. Will be either "text" (free-form text field), "checkbox" (boolean value), or "option" (dropdown list).
options array Array of name-value pairs corresponding to the options defined for this field. (Empty for "text" or "checkbox" field types.)

Examples

JSON

[
  {
    "id":"dba67b156f77123fb413ddfa3dc4ac1d",
    "name":"Cost Center",
    "isRequired":false,
    "type":"text",
    "options":[]
  },
  {
    "id":"58f83af6123846769ee6cb091ce3561e",
    "name":"Production",
    "isRequired":true,
    "type":"checkbox",
    "options":[]
  },
  {
    "id":"22f002123e3b46d9a8b38ecd4c6df7f9",
    "name":"Color",
    "isRequired":true,
    "type":"option",
    "options":[
      {
        "name":"red",
        "value":"Red"
      },
      {
        "name":"blue",
        "value":"Blue"
      }
    ]
  }
]

Get Data Center Bare Metal Capabilities

Gets the list of bare metal capabilities that a specific data center supports for a given account, including the list of configuration types and the list of supported operating systems. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of related to provisioning bare metal servers in a data center for your account. Specifically, this operation is helpful for retrieving the list of configuration identifiers and OS types to use when creating a bare metal server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/bareMetalCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/VA1/bareMetalCapabilities

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Réponse

Entity Definition

Name Type Description
skus array Collection of available bare metal configuration types to pass in to configurationId when creating a bare metal server
operatingSystems array Collection of available operating systems when creating a bare metal server

SKUs Definition

Name Type Description
id chaîne The configurationId to pass to the Create Server API operation when creating a bare metal server.
hourlyRate nombre Price per hour for the given configuration.
availability chaîne The level of availability for the given configuration: either high, low, or none.
memory array Information about the memory on the server.
processor complex Information about the physical processors on the server.
stockage array Collection of disk information, each item representing one physical disk on the server.

Memory Definition

Name Type Description
capacityGB nombre Memory capacity in gigabytes

Processor Definition

Name Type Description
coresPerSocket nombre Number of cores for each processor socket
description chaîne Description of the processor including model and clock speed
sockets nombre Number of sockets

Storage Definition

Name Type Description
capacityGB nombre Drive capacity in gigabytes
speedRpm nombre RPM (revolutions per minutes) speed of the disk
type chaîne Disk type. Only Hdd currently supported.

OperatingSystems Definition

Name Type Description
type chaîne Underlying unique name for the OS type
description chaîne Friendly description for the OS type
hourlyRatePerSocket nombre Price per hour per socket for the OS type.

Examples

JSON

{
  "skus": [
    {
      "id": "529e2592a3e640a7c2617b5e8bc8feaed95eab22",
      "hourlyRate": 0.56,
      "availability": "high",
      "memory": [
        {
          "capacityGB": 16
        }
      ],
      "processor": {
        "coresPerSocket": 4,
        "description": "Intel(R) Xeon(R) CPU E3-1271 v3 @ 3.60GHz",
        "sockets": 1
      },
      "storage": [
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    },
    {
      "id": "f24b18ba2ce23657657444601649c7b8b7f9b60c",
      "hourlyRate": 1.65,
      "availability": "none",
      "memory": [
        {
          "capacityGB": 64
        }
      ],
      "processor": {
        "coresPerSocket": 6,
        "description": "Intel(R) Xeon(R) CPU E5-2620 v3 @ 2.40GHz",
        "sockets": 2
      },
      "storage": [
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    }
  ],
  "operatingSystems": [
    {
      "type": "centOS6_64Bit",
      "description": "CentOS 6 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "redHat6_64Bit",
      "description": "RedHat Enterprise Linux 6 64-bit",
      "hourlyRatePerSocket": 0.075
    },
    {
      "type": "ubuntu14_64Bit",
      "description": "Ubuntu 14 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "windows2012R2Standard_64bit",
      "description": "Windows 2012 R2 Standard 64-bit",
      "hourlyRatePerSocket": 0.04
    },
    {
      "type": "windows2012R2Datacenter_64bit",
      "description": "Windows 2012 R2 Datacenter 64-bit",
      "hourlyRatePerSocket": 0.279
    }
  ]
}

Get Data Center Deployment Capabilities

Gets the list of capabilities that a specific data center supports for a given account, including the deployable networks, OS templates, and whether features like shared load balancer configuration are available. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of a data center for your account. Specifically, this operation is helpful for retrieving network identifiers and OS template names to use when creating a server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/deploymentCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1/deploymentCapabilities

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Réponse

Entity Definition

Name Type Description
supportsSharedLoadBalancer boolean Whether or not this data center provides support for shared load balancer configuration
supportsBareMetalServers boolean Whether or not this data center provides support for provisioning bare metal servers
deployableNetworks array Collection of networks that can be used for deploying servers
templates array Collection of available templates in the data center that can be used to create servers
importableOSTypes array Collection of available OS types that can be imported as virtual machines.

DeployableNetworks Definition

Name Type Description
nom chaîne User-defined name of the network
networkId chaîne Unique identifier of the network
type chaîne Network type, usually "private" for networks created by the user
accountID chaîne Account alias for the account in which the network exists

Templates Definition

Name Type Description
nom chaîne Underlying unique name for the template
description chaîne Description of the template at it appears in the Control Portal UI
storageSizeGB integer The amount of storage allocated for the primary OS root drive
capabilities array List of capabilities supported by this specific OS template (example: whether adding CPU or memory requires a reboot or not)
reservedDrivePaths array List of drive path names reserved by the OS that can't be used to name user-defined drives
drivePathLength integer Length of the string for naming a drive path, if applicable

Examples

JSON

{
  "supportsBareMetalServers":false,
  "supportsSharedLoadBalancer":true,
  "deployableNetworks":[
    {
      "name":"My Network",
      "networkId":"a933432bd8894e84b6c4fb123e48cb8b",
      "type":"private",
      "accountID":"ACCT"
    }
  ],
  "templates":[
    {
      "name":"UBUNTU-14-64-TEMPLATE",
      "description":"Ubuntu 14 | 64-bit",
      "storageSizeGB":17,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    },
    {
      "name":"WIN2012R2DTC-64",
      "description":"Windows 2012 R2 Datacenter Edition | 64-bit",
      "storageSizeGB":60,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "a",
        "b",
        "c",
        "d"
      ],
      "drivePathLength":1
    },
    {
      "name":"WA1ACCTCUST01",
      "description":"My Custom Template",
      "storageSizeGB":16,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    }
  ]
}

Get Data Center List

Gets the list of data centers that a given account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of data center names and codes that you have access to. Using that list of data centers, you can then query for the root group, and all the child groups in an entire data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}

Example

GET https://api.ctl.io/v2/datacenters/ALIAS

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Réponse

Entity Definition

Name Type Description
id chaîne Short value representing the data center code
nom chaîne Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

[
  {
    "id": "DC1",
    "name": "DC FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC1"
      }
    ]
  },
  {
    "id": "DC2",
    "name": "DC2 FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC2"
      }
    ]
  }
]

Get Data Center

Gets the details of a specific data center the account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the name of the root hardware group for a data center. Once you have that group alias, you can issue a secondary query to retrieve the entire group hierarchy for a given data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}?groupLinks=true|false

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1?groupLinks=true

Requête

URI and Querystring Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
GroupLinks boolean Determine whether link collections are returned for each group Non

Réponse

Entity Definition

Name Type Description
id chaîne Short value representing the data center code
nom chaîne Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "id": "DC1",
  "name": "DC FRIENDLY NAME",
  "links": [
    {
      "rel": "self",
      "href": "/v2/datacenters/ALIAS/DC1"
    },
    {
      "rel":"group",
      "href":"/v2/groups/ALIAS/54faef9c2bfd41d6b30f787567f9b0d4",
      "id":"54faef9c2bfd41d6b30f787567f9b0d4",
      "name":"DC1 Hardware"
    }
  ]
}

Add Public IP Address

Claims a public IP address and associates it with a server, allowing access to it on a given set of protocols and ports. It may also be set to restrict access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a public IP address to an existing server. The public IP can be exposed on multiple protocols and ports and also be set to restrict access based on source IP ranges.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
internalIPAddress chaîne The internal (private) IP address to map to the new public IP address. If not provided, one will be assigned for you. Non
ports array The set of ports and protocols to allow access to for the new public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address claimed here. Oui
sourceRestrictions array The source IP address range allowed to access the new public IP address. Used to restrict access to only the specified range of source IPs. Non

Ports Definition

Name Type Description
protocol chaîne The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr chaîne The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create a Cross Data Center Firewall Policy

Creates a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy between networks in different data centers for a given account.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Content Properties

Name Type Description Req.
destinationAccountId chaîne Short code for a particular account Oui
destinationLocationId chaîne Short code for a particular location Oui
destinationCidr chaîne Destination address for traffic on the terminating firewall, specified using CIDR notation Oui
activé chaîne Indicates if the policy is enabled (true) or disabled (false) Oui
sourceCidr chaîne Source address for traffic on the originating firewall, specified using CIDR notation, on the originating firewall Oui

Example

JSON

{
    "destinationAccountId" : "dest",
    "destinationLocationId" : "UC1",
    "destinationCidr" : "10.1.1.0/24",
    "enabled" : true,
    "sourceCidr" : "10.2.2.0/24"
}

Réponse

The response will be an entity representing the new firewall policy that was created.

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "pending",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Create an Intra Data Center Firewall Policy

Creates a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Content Properties

Name Type Description Req.
destinationAccount chaîne Short code for a particular account Oui
source chaîne Source addresses for traffic on the originating firewall, specified using CIDR notation, on the originating firewall Oui
destination chaîne Destination addresses for traffic on the terminating firewall, specified using CIDR notation Oui
ports chaîne Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP). Non

Examples

JSON

{
    "destinationAccount": "DEST_ALIAS",
    "source":["123.45.223.1/32", "123.45.223.2/32", "123.45.223.3/32"],
    "destination":["123.45.223.1/32", "123.45.223.2/32"],
    "ports":["tcp/1-600"]
}

Réponse

The response will be an entity representing the new firewall policy that was created.

Entity Definition

Name Type Description
links array Collection of entity links that point to resources related to this firewall policy

Examples

JSON

{
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/DEST_ALIAS/WA1/71f912d00e1c11e5b9390800200c9a66",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Delete a Cross Data Center Firewall Policy

Deletes a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Oui
policyId chaîne ID of the firewall policy Oui

Réponse

There is no response upon the successful removal of the firewall policy.

Delete an Intra Data Center Firewall Policy

Deletes a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Oui
firewallPolicy chaîne ID of the firewall policy Oui

Réponse

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful removal of the firewall policy.

Get Cross Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account, between networks in different data centers ("cross data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountId}/{dataCenter}?destinationAccountId={destinationAccountId}

Example

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1?destinationAccountId=DEST_ALIAS

Requête

URI Parameters

Name Type Description Req.
sourceAccountId chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Oui
destinationAccountId chaîne Short code for another account Non

Réponse

Example

JSON

[
 {
   "id": "921670344d781378a8df6159c00bddea",
   "status": "pending",
   "enabled": true,
   "sourceCidr": "10.2.2.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "1a4b72963130e7a4d1a3343299f84edc",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.5.5.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest1",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src5/wa1/1a4b72963130e7a4d1a3343299f84edc",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "372d37109487b0584db2c87b16f654b1",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.7.7.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.9.9.0/24",
   "destinationAccount": "dest2",
   "destinationLocation": "il1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src7/gb3/372d37109487b0584db2c87b16f654b1",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 }
]

Get Cross Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
policyId chaîne ID of the firewall policy Oui

Réponse

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "active",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Intra Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account in a given data center ("intra data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies in a given data center for a given account. Using that list of firewall policies, you can then query for a specific policy in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}?destinationAccount={destinationAccountAlias}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1?destinationAccount=DEST_ALIAS

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
destinationAccountAlias chaîne Short code for a particular account Non

Réponse

Entity Definition

Name Type Description
id chaîne ID of the firewall policy
status chaîne The state of the policy: either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
activé boolean Indicates if the policy is enabled (true) or disabled (false)
source chaîne Source addresses for traffic on the originating firewall, specified using CIDR notation
destination chaîne Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount chaîne Short code for a particular account
ports chaîne Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

[
    {
        "id": "c59b96600e0d11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32",
            "123.45.678.2/32",
            "123.45.678.3/32"
        ],
        "destination": [
            "234.56.789.1/32",
            "234.56.789.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/c59b96600e0d11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "bbb377290e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": false,
        "source": [
            "145.67.890.1/32",
            "145.67.890.2/32",
            "145.67.890.3/32"
        ],
        "destination": [
            "156.78.901.1/32",
            "156.78.901.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/bbb377290e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "d56587800e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32"
        ],
        "destination": [
            "234.23.435.200/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "tcp/8080",
            "tcp/1-8000"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/d56587800e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
]

Get Intra Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
firewallPolicy chaîne ID of the firewall policy Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the firewall policy
status chaîne The state of the policy; either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
activé boolean Indicates if the policy is enabled (true) or disabled (false)
source chaîne Source addresses for traffic on the originating firewall, specified using CIDR notation
destination chaîne Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount chaîne Short code for a particular account
ports chaîne Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

{
    "id": "1ac853b00e1011e5b9390800200c9a6",
    "status": "active",
    "enabled": true,
    "source": [
        "123.45.678.1/32",
        "123.45.678.2/32",
        "123.45.678.3/32"
    ],
    "destination": [
        "245.21.223.1/32",
        "245.21.223.2/32"
    ],
    "destinationAccount": "DEST_ALIAS",
    "ports": [
        "any"
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a6",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Public IP Address

Gets the details for the public IP address of a server, including the specific set of protocols and ports allowed and any source IP restrictions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out information about a specific public IP address for an existing server. This operation is linked to from the Get Server response that lists all public IPs assigned to a server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui
PublicIP chaîne The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Oui

Réponse

Entity Definition

Name Type Description
internalIPAddress chaîne The internal (private) IP address mapped to the public IP address.
ports array The set of accessible ports and protocols for the public IP address.
sourceRestrictions array The source IP address range allowed to access the new public IP address. Only traffic from this range will have access to the public IP on the specified ports.

Ports Definition

Name Type Description
protocol chaîne The specific protocol to support for the given port(s). Should be either "tcp", "udp", or "icmp" (which is enabled by default).
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr chaîne The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "internalIPAddress":"10.11.12.13",
  "ports":[
    {
      "protocol":"ICMP",
      "port":0
    },
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Remove Public IP Address

Releases the given public IP address of a server so that it is no longer associated with the server and available to be claimed again by another server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to stop using a specific public IP address on an existing server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui
PublicIP chaîne The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Oui

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will no longer be associated with the server.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Update Cross Data Center Firewall Policy

Updates a given firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}?enabled=true/false

Example

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea?enabled=false

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation. Oui
activé chaîne true or false Oui

Réponse

There is no response upon the successful update of the firewall policy.

Update Intra Data Center Firewall Policy

Updates a given firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

PUT https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/e46ef2500e1011e5b9390800200c9a66

Requête

URI Parameters

Name Type Description Req.
sourceAccountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation. Oui
destinationAccountAlias chaîne Short code for a particular account Non

Content Properties

Name Type Description Req.
activé boolean Indicates if the policy is enabled (true) or disabled (false) Non
source chaîne Source addresses for traffic on the originating firewall, specified using CIDR notation Non
destination chaîne Destination addresses for traffic on the terminating firewall, specified using CIDR notation Non
ports chaîne Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP). Non

Examples

JSON

{
    "enabled":false,
    "source":["123.45.678.1/32"],
    "destination":["234.4.678.2/32"],
    "ports":["udp/8080"]
}

Réponse

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of firewall policy attributes.

Update Public IP Address

Updates a public IP address on an existing server, allowing access to it on a given set of protocols and ports as well as restricting access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to update the ports and protocols or source IP restrictions for a public IP address on an existing server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

PUT https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui
PublicIP chaîne The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Oui

Content Properties

Name Type Description Req.
ports array The set of ports and protocols to allow access to for the public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address specified here. Oui
sourceRestrictions array The source IP address range allowed to access the public IP address. Used to restrict access to only the specified range of source IPs. Non

Ports Definition

Name Type Description
protocol chaîne The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr chaîne The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create Group

Creates a new group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}

Example

POST https://api.ctl.io/v2/groups/ALIAS/

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the group to create. Oui
description chaîne User-defined description of this group Non
parentGroupId chaîne ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Oui
customFields complex Collection of custom field ID-value pairs to set for the server. Non

CustomFields Definition

Name Type Description
id chaîne ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value chaîne Value to set the custom field to for this server.

Examples

JSON

{
  "name": "New Group",
  "description": "A new group.",
  "parentGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "customFields": [
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "value": "1100003"
    }
  ]
}

Réponse

Group Entity Definition

Name Type Description
id chaîne ID of the group being queried
nom chaîne User-defined name of the group
description chaîne User-defined description of this group
locationId chaîne Data center location identifier
type chaîne Group type which could include system types like "archive"
status chaîne Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the group was created
createdBy chaîne Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy chaîne Who modified the group last

CustomFields Definition

Name Type Description
id chaîne Unique ID of the custom field
nom chaîne Friendly name of the custom field
value chaîne Underlying value of the field
displayValue chaîne Shown value of the field

Examples

JSON

{
  "id": "56b789a2a72f43a98ae2227061e8f8f8",
  "name": "New Group",
  "description": "A new group.",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "groups": [
    {
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Parent Group Name",
      "description": "The parent group.",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities",
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/scheduledActivities"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Delete Group

Sends the delete operation to a given group and adds operation to queue. This operation will delete the group and all servers and groups underneath it. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a group and all objects underneath it.

URL

Structure

DELETE https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

DELETE https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupId chaîne ID of the group to be deleted. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Oui

Réponse

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Get Group Billing Details

Gets the current and estimated charges for each server in a designated group hierarchy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out the charges associated with a specific group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/billing

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/billing

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal Oui

Réponse

Group Entity Definition

Name Type Description
date datetime Date that this billing information applies to
groups array List of groups (with the first being the queried group) in the requested hierarchy. Group ID listed before each group entity description

Groups Definition

Name Type Description
nom chaîne User-defined name of the group
servers array Collection of servers in this group, each with billing information. Server ID listed before each entity description

Servers Definition

Name Type Description
templateCost float Cost of templates stored in the group
archiveCost float Cost of archived servers in this group
monthlyEstimate float Projected charges for the servers given current usage
monthToDate float Charges up until the requested time
currentHour float Charges for the most recent hour

Examples

JSON

{
  "date": "2014-04-07T21:33:51.9743015Z",
  "groups": {
    "8c95fbaf74b7497fb671235aa318b44c": {
      "name": "Web Applications",
      "servers": {
        "wa1acctserv7101": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 77.76,
          "monthToDate": 17.93,
          "currentHour": 0.108
        },
        "wa1acctserv7202": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 156.96,
          "monthToDate": 36.19,
          "currentHour": 0.218
        }
      }
    },
    "4bca7bf6ead14cd59053e1eb1cd2d01f": {
      "name": "Training Environment",
      "servers": {}
    }
  }
}

Get Group Horizontal Autoscale Policy

Retrieves the details of a horizontal autoscale policy associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a horizontal autoscale policy associated to a Group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Oui

Réponse

Name Type Description
groupId chaîne ID of the group
policyId chaîne The unique identifier of the autoscale policy
locationId chaîne Data center location identifier
nom chaîne Name of the Policy
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection chaîne Direction to Scale (In or Out )
scaleResourceReason chaîne Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex Information about the load balancer associated with the policy
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type Description
id chaîne ID of the load balancer
nom chaîne Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP chaîne The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "Up",
  "scaleResourceReason": "MinimumResourceCount",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 443,
    "privatePort": 300,
    "publicIP": "1.1.1.1",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "timestamp": "2015-10-20T21:20:02Z",
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/WHIM/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Get Group Monitoring Statistics

Gets the resource consumption details for whatever window specified in the request. Data can be retrieve for a variety of time windows and intervals. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to track the resource usage of servers within a group hierarchy. It can be used to populate a local data mart or chart the results on a dashboard.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/statistics?type=hourly&start={datetime}&end={datetime}&sampleInterval={dd:hh:mm:ss}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/statistics?type=hourly&start=2014-04-05T07:52:47.302Z&end=2014-04-07T07:52:47.302Z&sampleInterval=01:00:00

Requête

URI and Querystring Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Oui
type chaîne Valid values are latest, hourly, or realtime.

latest will return a single data point that reflects the last monitoring data collected. No start, end, or sampleInterval values are required for this type.

hourly returns data points for each sampleInterval value between the start and end times provided. The start and sampleInterval parameters are both required for this type.

realtime will return data from the last 4 hours, available in smaller increments. To use realtime type, start parameter must be within the last 4 hours. The start and sampleInterval parameters are both required for this type.
Oui
start datetime DateTime (UTC) of the query window. Note that statistics are only held for 14 days. Start date (and optional end date) must be within the past 14 days. Value is not required if choosing the latest query type. Yes, except for latest type
end datetime DateTime (UTC) of the query window. Default is the current time in UTC. End date (and start date) must be within the past 14 days. Not a required value if results should be up to the current time. Non
sampleInterval timespan Result interval. For the default hourly type, the minimum value is 1 hour (01:00:00) and maximum is the full window size of 14 days. Note that interval must fit within start/end window, or you will get an exception that states: "The 'end' parameter must represent a time that occurs at least one 'sampleInterval' before 'start.'" If realtime type is specified, interval can be as small as 5 minutes (05:00). Yes, except for latest type

Réponse

Entity Definition

Name Type Description
nom chaîne Name of the server
stats array Collection of stats for the server for the interval chosen

Stats Definition

Name Type Description
timestamp datetime Timestamp of the monitoring results
cpu float CPU allocation during the interval
cpuPercent float CPU consumption (out of 100%) during the interval
memoryMB float Memory allocation during the interval
memoryPercent float Memory consumption (out of 100%) during the interval
networkReceivedKbps float Public network consumption in during the interval
networkTransmittedKbps float Public network consumption out during the interval
diskUsageTotalCapacityMB float Total disk allocation during the interval
diskUsage array List of physical disks attached to the virtual machine
guestDiskUsage array List of partitions used inside the guest OS

Disk Usage Definition

Name Type Description
id chaîne Disk identifier
capacityMB integer Capacity (in MB) allocated for this disk

Guest Usage Definition

Name Type Description
path chaîne Path of this partition
capacityMB integer Total capacity available to this partition
consumedMB integer Amount of capacity in use by this partition

Examples

JSON

(/v2/groups/ALIAS/GROUP/statistics?start=2014-04-09T20:00:00&sampleInterval=01:00:00)

[
  {
    "name": "wa1acctser7101",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 5.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 2.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      }
    ]
  },
  {
    "name": "wa1acctser7202",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.14,
        "memoryMB": 2048.0,
        "memoryPercent": 9.24,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.02,
        "memoryMB": 2048.0,
        "memoryPercent": 2.32,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      }
    ]
  }
]

Get Group Scheduled Activities

Gets the scheduled activities associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the scheduled activities for a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Oui

Réponse

Name Type Description
id chaîne ID of the group
locationId chaîne Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status chaîne State of scheduled activity: on or off
type chaîne Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUtc datetime Time when scheduled activity should start
repeat chaîne How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire chaîne When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUtc datetime When the scheduled activity should expire
timeZoneOffset chaîne To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run

Examples

JSON

[
  {
    "id": "95715f96f8a145d68ace797fe542c9ae",
    "locationId": "WA1",
    "changeInfo": {
      "createdBy": "john.doe",
      "createdDate": "2015-03-16T18:12:02Z",
      "modifiedBy": "john.doe",
      "modifiedDate": "2015-10-20T22:20:25Z"
    },
    "links": [
      {
        "rel": "group",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8",
        "id": "fc06fd421e2ee41190460050568600e8",
        "name": "Default Group"
      },
      {
        "rel": "self",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/scheduledActivities/95715f96f8a145d68ace797fe542c9ae",
        "verbs": [
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    ],
    "status": "on",
    "type": "shutdown",
    "beginDateUTC": "2015-03-16T18:11:00Z",
    "repeat": "customWeekly",
    "customWeeklyDays": [
      "tue",
      "thu"
    ],
    "expire": "never",
    "timeZoneOffset": "-07:00:00",
    "isExpired": false,
    "occurrenceCount": 0,
    "nextOccurrenceDateUTC": "2015-10-22T18:11:00Z"
  }
]

Get Group

Gets the details for a individual server group and any sub-groups and servers that it contains. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to identify the servers in a particular group, retrieve a group hierarchy, or get links to information (e.g. billing, monitoring, scheduled activities) about a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Oui

Réponse

Group Entity Definition

Name Type Description
id chaîne ID of the group being queried
nom chaîne User-defined name of the group
description chaîne User-defined description of this group
locationId chaîne Data center location identifier
type chaîne Group type which could include system types like "archive"
status chaîne Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the group was created
createdBy chaîne Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy chaîne Who modified the group last

CustomFields Definition

Name Type Description
id chaîne Unique ID of the custom field
nom chaîne Friendly name of the custom field
value chaîne Underlying value of the field
displayValue chaîne Shown value of the field

Examples

JSON

{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "name": "Web Applications",
  "description": "public facing web apps",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "serversCount": 2,
  "groups": [
    {
      "id": "31d13f501459411ba59304f3d47486eb",
      "name": "Training Environment",
      "description": "Temporary servers",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/231c3f3fec0e46499290b351199d555f",
          "id": "231c3f3fec0e46499290b351199d555f"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/8a03fcae8dd65411b05f00505682315a/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/31d13f501459411ba59304f3d47486eb/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/scheduledActivities"
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/540494152d0c4a9ab61869562b4c1471",
      "id": "540494152d0c4a9ab61869562b4c1471"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities"
    },
    {
      "rel": "server",
      "href": "/v2/servers/acct/wa1acctpre7101",
      "id": "WA1ACCTPRE7101"
    },
    {
      "rel": "server",
      "href": "/v2/servers/btdi/wa1acctpre7202",
      "id": "WA1ACCTPRE7202"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Set Group Custom Fields

Changes the custom field values for an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupId chaîne ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the group. In this case, the value must be "set" for setting the custom field values.
member chaîne The property of the group to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the group. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Group call to see all the details of the group or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Defaults

Sets the defaults for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set defaults for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/defaults

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/defaults

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Oui

Content Properties

Name Type Description Req.
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers) Non
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers) Non
networkId chaîne ID of the Network. This can be retrieved from the Get Network List API operation. Non
primaryDns chaîne Primary DNS to set on the server. If not supplied the default value set on the account will be used. Non
secondaryDns chaîne Secondary DNS to set on the server. If not supplied the default value set on the account will be used. Non
templateName chaîne Name of the template to use as the source. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.) Non

Examples

JSON

{
  "cpu": "1",
  "memoryGB": "2",
  "networkId": "fb46f06f8278421d8e94d78cf6409ba5",
  "primaryDns": "8.8.8.8",
  "secondaryDns": "8.8.4.4",
  "templateName": "UBUNTU-10-64-TEMPLATE"
}

Réponse

Cpu Definition

Name Type Description
value int How many vCPUs are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Memory Definition

Name Type Description
value int How many GB of memory are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Network Definition

Name Type Description
value chaîne ID of the Network
inherited bool Whether the value is set explicitly (false) or by its parent (true)

PrimaryDNS Definition

Name Type Description
value chaîne Primary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

SecondaryDNS Definition

Name Type Description
value chaîne Secondary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

TemplateName Definition

Name Type Description
value chaîne ID
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Examples

JSON

{
  "cpu": {
    "value": 1,
    "inherited": false
  },
  "memoryGB": {
    "value": 2,
    "inherited": false
  },
  "networkId": {
    "value": "ee600a2b4b734aac8ab0de2642597433",
    "inherited": true
  },
  "primaryDns": {
    "value": "8.8.8.8",
    "inherited": false
  },
  "secondaryDns": {
    "value": "8.8.4.4",
    "inherited": false
  },
  "templateName": {
    "value": "UBUNTU-10-64-TEMPLATE",
    "inherited": false
  }
}

Set Group Horizontal Autoscale Policy

Applies a horizontal autoscale policy to a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to apply a horizontal autoscale policy to a group.

URL

Structure

PUT https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

PUT https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Oui

Content Properties

Name Type Description Req.
policyId chaîne The unique identifier of the autoscale policy Oui
loadBalancerPool complex Information about the load balancer Oui

Load Balancer Pool

Name Type Description Req.
id chaîne ID of the load balancer Oui
publicPort int Port configured on the public-facing side of the load balancer pool. Oui
privatePort int The internal (private) port of the node server Oui

Example

{
  "policyId" : "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "loadBalancerPool" :  
  {
    "id" : "bf82320cc96d42048fc7d5e41b0cdada",
    "privatePort" : 80,
    "publicPort" : 80
  }
}

Réponse

Name Type Description
groupId chaîne ID of the group
policyId chaîne The unique identifier of the autoscale policy
locationId chaîne Data center location identifier
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection chaîne Direction to Scale (In or Out )
scaleResourceReason chaîne Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type Description
id chaîne ID of the load balancer
nom chaîne Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP chaîne The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Example

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "None",
  "scaleResourceReason": "Cpu",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 80,
    "privatePort": 80,
    "publicIP": "63.251.170.219",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Set Group Name/Description

Changes the name and description of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name or description of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupId chaîne ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the group. In this case, the value must be "set" for setting the name and description.
member chaîne The property of the group to perform the operation on. In this case, the value will be either "name" or "description".
value chaîne The value to set for the given member. This is the name or description to set for the group.

Examples

JSON

[
   {
      "op":"set",
      "member":"name",
      "value":"New Name"
   },
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Parent

Changes the parent group of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the parent of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
GroupId chaîne ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the group. In this case, the value must be "set" for setting the parent group.
member chaîne The property of the group to perform the operation on. In this case, the value will be "parentGroupId".
value chaîne The value to set for the given member. This is the group identifier for the new parent group.

Examples

JSON

[
   {
      "op":"set",
      "member":"parentGroupId",
      "value":"af7552c50e1b40b28d8023ed5eeaa74c"
   }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Scheduled Activities

Sets scheduled activities for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set scheduled activities for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
GroupID chaîne ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Oui

Content Properties

Name Type Description Req.
status chaîne State of scheduled activity: on or off Oui
type chaîne Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown Oui
beginDateUTC datetime Time when scheduled activity should start Oui
repeat chaîne How often to repeat: never, daily, weekly, monthly, customWeekly Oui
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat Non
expire chaîne When the scheduled activities are set to expire: never, afterDate, afterCount Oui
expireCount int Number of times scheduled activity should run before expiring Non
expireDateUTC datetime When the scheduled activity should expire Non
timeZoneOffset chaîne To display in local time Oui

Examples

JSON

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:41:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "weekly",
  "expire": "never"
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:40:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "customWeekly",
  "expire": "never",
  "customWeeklyDays": [
    "mon",
    "wed",
    "fri"
  ]
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T21:27:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "daily",
  "expire": "afterCount",
  "expireCount": "10"
}

Réponse

Name Type Description
id chaîne ID of the group
locationId chaîne Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status chaîne State of scheduled activity: on or off
type chaîne Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUTC datetime Time when scheduled activity should start
repeat chaîne How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire chaîne When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUTC datetime When the scheduled activity should expire
timeZoneOffset chaîne To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run
{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "locationId": "WA1",
  "changeInfo": {
    "createdBy": "user@user.com",
    "createdDate": "2015-11-23T21:17:16Z",
    "modifiedBy": "user@user.com",
    "modifiedDate": "2015-11-23T21:17:16Z"
  },
  "links": [
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Default Group Name"
    },
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/5b824632e319e411929e00505682315a/scheduledActivities/2a5c0b9662cf4fc8bf6180f139facdc0",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ],
  "status": "on",
  "type": "pause",
  "beginDateUTC": "2015-11-23T19:41:00Z",
  "repeat": "daily",
  "customWeeklyDays": [],
  "expire": "never",
  "timeZoneOffset": "-08:00:00",
  "isExpired": false,
  "occurrenceCount": 0,
  "nextOccurrenceDateUTC": "2015-11-24T19:41:00Z"
}

Archive Group

Sends the archive operation to a group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive an entire group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/archive

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/archive

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui
GroupID chaîne ID of the group to archive. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Oui

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the group will be archived as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Restore Group

Sends the restore operation to an archived group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore an archived group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/restore

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/restore

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui
GroupID chaîne ID of the group to restore. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Oui

Content Properties

Name Type Description Req.
targetGroupId chaîne The unique identifier of the target group to restore the group to. Oui

Réponse

Entity Definition

Name Type Description
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this group operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "isQueued":true,
  "links":[
    {
      "rel":"self",
      "href":"/v2/groups/bryf/2a5c0b9662cf4fc8bf6180f139facdc0?AccountAlias=ALIAS&identifier=2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel":"status",
      "href":"/v2/operations/bryf/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Configure Intrusion Protection Service Notifications

Configures notifications associated with an IPS agent running on a designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to configure the notifications of an installed IPS agent on CenturyLink Cloud servers.

The calls below will perform all of the operations for configuring, retrieving, updating, and deleting a notification destination.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

Create and Update

PUT https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Retrieve

GET https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Suppression

DELETE https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Example

PUT https://api.client-security.ctl.io/ips/api/notifications/ALIAS/VA1ALIASTEST04

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverName chaîne The name of the server that has the agent already installed Oui

Content Properties

Name Type Description Req.
notificationDestinations array List of Notification Destinations Oui

Notification Destination Definition

Name Type Description Req.
url chaîne The URL endpoint for WEBHOOK or SLACK notification Non
typeCode chaîne This is the type of destination (either SYSLOG, EMAIL, or WEBHOOK) Oui
sysLogSettings array This contains all of the options for SYSLOG Non
emailAddress chaîne This object will contain options for an EMAIL notification Non

SysLogSettings Definition

Name Type Description Req.
ipAddress chaîne The IP address of customers syslog server Oui
udpPort integer The port the syslog is listening on Oui
facility integer This is an Integer, 16-23, to set the type of program logging messages. Oui

Example

PUT http://api.client-security.ctl.io/ips/api/notification/ALIAS/VA1ALIASMYSVR01

{
    "url": "http://my.slack.webhook",
    "typeCode": "SLACK"
},
{
    "url": "http://my.generic.webhook",
    "typeCode": "WEBHOOK"
},
{
    "typeCode": "SYSLOG",
    "sysLogSettings":
        {
            "ipAddress": "12345",
            "udpPort": "8081",
            "facility": "16"
        }
},
{
    "typeCode": "EMAIL",
    "emailAddress": "youremail@site.com"
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response. For details on what's included in each alert, please refer to this knowledge base article.

Install Intrusion Protection Service Agent

Installs an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to install an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

POST https://api.client-security.ctl.io/ips/api/app/

Example

POST https://api.client-security.ctl.io/ips/api/app/

Requête

Content Properties

Name Type Description Req.
hostName chaîne The name of the server that will ha Data center location of the anti-affinity policy. Oui
accountAlias chaîne Short code for a particular account Oui

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the install of the agent.

Uninstall Intrusion Protection Service Agent

Uninstalls an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to uninstall an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

DELETE https://api.client-security.ctl.io/ips/api/app/

Example

DELETE https://api.client-security.ctl.io/ips/api/app/

Requête

URI Parameters

Name Type Description Req.
hostName chaîne The name of the server that is the target destination for the agent uninstall Oui
accountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
hostName chaîne The name of the server that will ha Data center location of the anti-affinity policy. Oui
accountAlias chaîne Short code for a particular account Oui

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the uninstall of the agent.

Claim Network

Claims a network for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to claim a network in a given data center you are able to access. Once you have a network, you can then perform various actions like getting IP addresses and updating its name.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/claim

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/claim

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Response [UPDATED JANUARY 19 2016]

Entity Definition

Name Type Description
operationId chaîne Unique identifier for network claim operation
uri chaîne URI to check status of operation

Examples

The initial response from the Claim Network API provides the unique identifier for the asynchronous operation to claim the network and a URI to check the status of that operation.

{
  "operationId": "c387aa9873ab4f7399ea8964dd61510d",
  "uri": "/v2-experimental/operations/{accountAlias}/status/{operationId}"
}

While the operation is executing, the response from the operation URI will provide a summary of the operation.

{
  "requestType": "blueprintOperation",
  "status": "running",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

When the operation completes successfully the response will provide a status property as "succeeded" and a link to the claimed network.

{
  "requestType": "blueprintOperation",
  "status": "succeeded",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}",
    "links": [
      {
        "rel": "network",
        "href": "/v2-experimental/networks/{accountAlias}/{locationAlias}/{networkId}",
        "id": "{networkId}"
      }
    ]
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

If the operation to claim a network were to fail, the response will come back with status "failed" along with the operation summary information.

{
  "requestType": "blueprintOperation",
  "status": "failed",
  "summary": {
    "blueprintId": 92123,
    "locationId": "{locationId}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:43:42Z"
  }
}

Get IP Address List

Gets the list of IP addresses for a network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of IP Addresses associated with a given network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/ipAddresses?type=claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses?type=claimed

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
Réseau chaîne ID of the Network. These can be retrieved from the Get Network List API operation Oui
type chaîne Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses) Non

Réponse

Entity Definition

Name Type Description
address chaîne An IP Address on the Network
claimed boolean Indicates claimed status of the address, either true or false
serveur chaîne ID of the server associated with the IP address, if claimed
type chaîne Indicates if the IP address is private, publicMapped, or virtual

Examples

JSON

[
    {
        "address": "11.22.33.12",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.13",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.14",
        "claimed": false,
        "type": "private"
    },
    {
        "address": "65.43.210.123",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "publicMapped"
    }
]

Get Network List

Gets the list of networks available for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available networks in a given data center you are able to access. Using that list of networks, you can then query for a specific network in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the network
cidr chaîne The network address, specified using CIDR notation
description chaîne Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway chaîne Gateway IP address of the network
nom chaîne User-defined name of the network; the default is the VLAN number combined with the network address
netmask chaîne A screen of numbers used for routing traffic within a subnet
type chaîne Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

[
    {
        "id": "711725920a1f4002ac49e634e1789206",
        "cidr": "12.34.0.0/24",
        "description": "vlan_9998_12.34.0",
        "gateway": "12.34.0.1",
        "name": "vlan_9998_12.34.0",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9998,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    },
    {
        "id": "ec6ff75a0ffd4504840dab343fe41077",
        "cidr": "11.22.33.0/24",
        "description": "vlan_9999_11.22.33",
        "gateway": "11.22.33.1",
        "name": "vlan_9999_11.22.33",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9999,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    }
]

Get Network

Gets the details of a specific network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover properties of a network in a data center. You may optionally query details of IP Addresses on this network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}?ipAddresses=none|claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077?ipAddresses=claimed

Requête

URI and Querystring Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
Réseau chaîne ID of the Network. This can be retrieved from the Get Network List API operation. Oui
ipAddresses chaîne Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "none" (returns details of the network only), "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses). Refer to Get IP Address List for the data shape of returned IP addresses. Non

Réponse

Entity Definition

Name Type Description
id chaîne ID of the network
cidr chaîne The network address, specified using CIDR notation
description chaîne Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway chaîne Gateway IP address of the network
nom chaîne User-defined name of the network; the default is the VLAN number combined with the network address
netmask chaîne A screen of numbers used for routing traffic within a subnet
type boolean Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

{
    "id": "ec6ff75a0ffd4504840dab343fe41077",
    "cidr": "11.22.33.0/24",
    "description": "vlan_9999_11.22.33",
    "gateway": "11.22.33.1",
    "name": "vlan_9999_11.22.33",
    "netmask": "255.255.255.0",
    "type": "private",
    "vlan": 9999,
    "ipAddresses": [
        {
            "address": "11.22.33.12",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "11.22.33.13",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "65.43.210.123",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "publicMapped"
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
            "verbs": [
                "GET",
                "PUT"
            ]
        },
        {
            "rel": "ipAddresses",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
            "verbs": [
                "GET"
            ]
        },
        {
            "rel": "release",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
            "verbs": [
                "POST"
            ]
        }
    ]
}

Release Network

Releases a network from a given account in a given data center to a pool for another user to claim. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you no longer need a network, and wish to to release it back a given data center. Before you can release a network, there must be no IP addresses claimed by servers.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/release

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
Réseau chaîne ID of the Network. This can be retrieved from the Get Network List API operation Oui

Réponse

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful release of the network.

Create a Site to Site VPN

Creates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a Site to Site VPN for a given account.

URL

Structure

POST https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

POST https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

Requête

URI Parameters

Name Type Description Req.
accountId chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
local chaîne Local site properties Oui
remote chaîne Remote site properties Oui
ike chaîne IKE properties Oui
ipsec chaîne IPSec properties Oui

Local Entity

Name Type Description Req.
locationAlias chaîne Short code for a particular location Oui
subnets chaîne Local address for Site to Site VPN, specified using CIDR notation Oui

Remote Entity

Name Type Description Req.
siteName chaîne Friendly name of the site Oui
deviceType chaîne Friendly name of the device type Oui
address chaîne Remote address for Site to Site VPN, specified using CIDR notation Oui
subnets chaîne Remote network address for Site to Site VPN, specified using CIDR notation Oui

IKE Entity

Name Type Description Option Req.
encryption chaîne Encryption algorithm aes128, aes192, aes256, tripleDES Oui
hashing chaîne Hashing algorithm sha1_96, sha1_256, md5 Oui
diffieHellmanGroup chaîne Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5 Oui
preSharedKey chaîne The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection Oui
lifetime chaîne Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400 Oui
mode chaîne Protocol mode main, aggressive Oui
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false Non
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false Non
remoteIdentity chaîne The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address Oui

IPSec Entity

Name Type Description Option Req.
encryption chaîne Encryption algorithm aes128, aes192, aes256, tripleDES Oui
hashing chaîne Hashing algorithm sha1_96, sha1_256, md5 Oui
protocol chaîne IPSec protocol esp, ah Oui
pfs chaîne PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5 Oui
lifetime chaîne Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400 Oui

Example

JSON

{
  "local": {
    "locationAlias": "WA1",            	  
    "subnets": [                          
      "10.10.10.0/24"
    ]
  },
  "remote": {
    "siteName": "API test",                
    "deviceType": "SRX and stuff",        
    "address": "1.2.3.4",
    "subnets": [                          
      "10.1.1.0/24"
    ]
  },
  "ike": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "diffieHelmanGroup": "group2",        
    "preSharedKey": "Password123",
    "lifetime": 28800,                    
    "mode": "main",                       
    "deadPeerDetection": false,
    "natTraversal": false,
    "remoteIdentity": null                
  },
  "ipsec": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "protocol": "esp",                    
    "pfs": "group2",                      
    "lifetime": 3600                      
  }
}

Réponse

The response will be an entity representing the new Site to Site VPN that was created.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "pendingTaskId": "",
    "accountAlias": "ACCT",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "local": {
   "locationAlias": "WA1",               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "Password123",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "protocol": "esp",                    
   "pfs": "group2",                      
   "lifetime": 3600                      
 }
}

Delete a Site to Site VPN

Deletes a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a Site to Site VPN for a given account.

URL

Structure

DELETE https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

DELETE https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Requête

URI Parameters

Name Type Description Req.
accountId chaîne Short code for a particular account Oui
vpnId chaîne ID of the VPN Oui

Réponse

The response will be the job ID in the Queue, for the Site to Site VPN that is to be deleted.

Example

JSON

"54851"

Get Details for a Site to Site VPN

Gets Details for a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get details for a Site to Site VPN for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Requête

URI Parameters

Name Type Description Req.
accountId chaîne Short code for a particular account Oui
vpnId chaîne ID of the VPN Oui

Réponse

The response will be an entity representing the details for a Site to Site VPN for a given account.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
    "accountAlias": "ACCT",
    "local": {
        "address": "4.3.2.1",
        "locationAlias": "WA1",
        "locationDescription": "WA1 - US West (Seattle)",
        "subnets": [
            "10.10.10.0/24"
        ]
    },
    "remote": {
        "siteName": "Montreal Office",                
        "deviceType": "Cisco ASA5520 v8.3",
        "address": "1.2.3.4",
        "subnets": [
            "10.1.1.0/24"
        ]
    },
    "ike": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "diffieHellmanGroup": "group2",
        "lifetime": 28800,
        "mode": "main",
        "deadPeerDetection": false,
        "natTraversal": false,
        "remoteIdentity": null
    },
    "ipsec": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "protocol": "esp",
        "pfs": "group2",
        "lifetime": 3600
    },
    "links": [
        {
            "rel": "self",
            "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
        }
    ]
}

Get Site to Site VPNs

Gets all Site to Site VPNs for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get a list Site to Site VPNs for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

Requête

URI Parameters

Name Type Description Req.
accountId chaîne Short code for a particular account Oui

Réponse

The response will be an entity representing the Site to Site VPNs for a given account.

Example

JSON

[
    {
        "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
        "changeInfo": {
            "createdBy": "username",
            "createdDate": "2016-06-14T16:22:51Z",
            "modifiedBy": "username",
            "modifiedDate": "2016-06-14T17:53:12Z"
        },
        "accountAlias": "ACCT",
        "local": {
            "address": "4.3.2.1",
            "locationAlias": "WA1",
            "locationDescription": "WA1 - US West (Seattle)",
            "subnets": [
                "10.10.10.0/24"
            ]
        },
        "remote": {
            "siteName": "Montreal Office",                
            "deviceType": "Cisco ASA5520 v8.3",
            "address": "1.2.3.4",
            "subnets": [
                "10.1.1.0/24"
            ]
        },
        "ike": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "diffieHellmanGroup": "group2",
            "lifetime": 28800,
            "mode": "main",
            "deadPeerDetection": false,
            "natTraversal": false,
            "remoteIdentity": null
        },
        "ipsec": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "protocol": "esp",
            "pfs": "group2",
            "lifetime": 3600
        },
        "links": [
            {
                "rel": "self",
                "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
            }
        ]
    }
]

Update a Site to Site VPN

Updates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a Site to Site VPN for a given account.

URL

Structure

PUT https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

PUT https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Requête

URI Parameters

Name Type Description Req.
accountId chaîne Short code for a particular account Oui
vpnId chaîne ID of the VPN Oui

Content Properties

Name Type Description Req.
local chaîne Local site properties Non
remote chaîne Remote site properties Non
ike chaîne IKE properties Non
ipsec chaîne IPSec properties Non

Local Entity

Name Type Description Req.
subnets chaîne Local address for Site to Site VPN, specified using CIDR notation Non

Remote Entity

Name Type Description Req.
siteName chaîne Friendly name of the site Non
deviceType chaîne Friendly name of the device type Non
address chaîne Remote address for Site to Site VPN, specified using CIDR notation Non
subnets chaîne Remote network address for Site to Site VPN, specified using CIDR notation Non

IKE Entity

Name Type Description Option Req.
encryption chaîne Encryption algorithm aes128, aes192, aes256, tripleDES Non
hashing chaîne Hashing algorithm sha1_96, sha1_256, md5 Non
diffieHelmanGroup chaîne Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5 Non
preSharedKey chaîne The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection Non
lifetime chaîne Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400 Non
mode chaîne Protocol mode main, aggressive Non
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false Non
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false Non
remoteIdentity chaîne The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address Non

IPSec Entity

Name Type Description Option Req.
encryption chaîne Encryption algorithm aes128, aes192, aes256, tripleDES Non
hashing chaîne Hashing algorithm sha1_96, sha1_256, md5 Non
protocol chaîne IPSec protocol esp, ah Non
pfs chaîne PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5 Non
lifetime chaîne Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400 Non

Example

JSON

{
  "ike": {
    "preSharedKey": "321drowssaP"
  }
}

Réponse

The response will be an entity representing the Site to Site VPN that was updated.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "pendingTaskId": "54847",
 "accountAlias": "ACCT",
 "local": {
   "address": "4.3.2.1",
   "locationAlias": "WA1",
   "locationDescription": "WA1 - US West (Seattle)"               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "321drowssaP",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
     "encryption": "aes128",
     "hashing": "sha1_96",
     "protocol": "esp",
     "pfs": "group2",
     "lifetime": 3600
 },
 "links": [
     {
         "rel": "self",
         "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"                      
 }
}

Update Network

Updates the attributes of a given Network via PUT. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name and description of a network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}

Example

PUT https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077

Requête

URI and Querystring Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
dataCenter chaîne Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Oui
Réseau chaîne ID of the Network. These can be retrieved from the Get Network List API operation Oui

Content Properties

Name Type Description Req.
nom chaîne User-defined name of the network; the default is the VLAN number combined with the network address Oui
description chaîne Description of VLAN, a free text field that defaults to the VLAN number combined with the network address Non

Examples

JSON

{
    "name": "VLAN for Development Servers",
    "description": "Development Servers on 11.22.33.0/24"
}

Réponse

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of network attributes.

Applying Patches to Operating Systems

This service allows the user to patch virtual machines to the latest available patches provided by the OS vendor, using the Execute Package API. It does not discriminate patches based on patch severity or any other vendor categorization. The package will kick off one or multiple attempts to apply patches, including a series of reboots. Reboots will cease and the execution will complete when there are no more patches to apply. Additional information on this capability is in this knowledge base article.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to patch operating systems with updates from OS vendors.

NOTE: Servers require Internet access to be patched. It is also recommended to place servers in Maintenance Mode before patching. Further, an API request can deploy against all VMs a user is authorized to administer under a single alias.

Systèmes d’exploitation pris en charge

Currently, the Operating Systems that may be updated with this service are show below:

  • CentOS 5
  • CentOS 6
  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Red Hat Enterprise Linux 7
  • Windows 2012
  • Windows 2012R2

Exceptions

  • Red Hat Enterprise Linux and CentOS: This service will exclude some updates. It will exclude kernel patches and nss packages.

Package Details

Systèmes d’exploitation Blueprint Name Script Package Name Package ID
Windows 2012 and 2012R2 Auto Patching Windows 2012 Auto Patching Windows 2012 b229535c-a313-4a31-baf8-6aa71ff4b9ed
Red Hat Enterprise Linux 5, 6, and 7 OR CentOS 5 and 6 Yum Update Script Yum Update c3c6642e-24e1-4c37-b56a-1cf1476ee360

Example

JSON

{
    "servers": [
        "WA1ALIASSERV0101"
    ],
    "package": {
        "packageId": "c3c6642e-24e1-4c37-b56a-1cf1476ee360",
        "parameters": {"patch.debug.mode": "false"

        }
    }
}

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

In addition, you will receive an email confirming that the patch was requested. A second email will be sent upon the successful application of the auto-patch capability.

Get Details of Patches Applied to a Server During a Single Execution

This services returns details on all attempted patches for a single execution against a server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied for a given execution to a server using the Patching-as-a-Service feature.

The response will contain information from the vendor about the patch and the status of the attempt.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{alias}/server/{serverID}/patch/{execution_id}

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/OSD/server/VA1OSDPATCH33/patch/VA1-132457

Requête

URI

Name Type Description
accountAlias chaîne Short code for a particular account
serverID chaîne ID of the server
execution_id chaîne Correlation ID for all the patches included with a single update execution, obtained from the Patch Summary response or emails regarding a patch request. The execution ID format will be aa#-######

Réponse

Name Type Description
execution_id chaîne The execution ID associated with a particular patch
status chaîne Either pending or completed
start_time dateTime When this value is superior to patches, indicates the start time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the start time of the patch.
end_time dateTime When this value is superior to patches, indicates the end time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the end time of the patch.
duration chaîne The minutes and seconds between the start and end time
begin_message chaîne "Update Process BEGIN"
end_message chaîne "Updating Complete"
patches Number Quantity of patches installed
patch_begin_message chaîne Identifies the Software or OS updated and the reference number (if Windows, KB#######) for that particular update
patch_end_message chaîne Result code established by Microsoft, defining the possible results of an install. These same codes will be used for other Operating Systems as well. https://msdn.microsoft.com/en-us/library/windows/desktop/aa387095(v=vs.85).aspx
status chaîne Status of an individual patch, either pending, completed, or failed

Get a Summary of All Patches Deployed to a Server

This service shows a history of all the patches deployed to a given server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied to a server using the Patching-as-a-Service feature.

The response will contain a high-level overview of all the patches installed for each execution and when they were applied.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{accountAlias}/server/{serverID}/patch

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/ALIAS/server/WA1ALIASSERV0101/patch

Requête

URI

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server Oui

Réponse

Name Type Description
execution_id chaîne The execution ID associated with a particular patch
status chaîne Either pending or completed
start_time date/Time Either the start time of the entire execution (which contains all initiations) or a particular initiation
end_time date/Time Either the end time of the entire execution (which contains all initiations) or a particular initiation
init_messages complex Shows the quantity of initiations
init_begin_message chaîne "Invoking SUS API" or "Invoking yum check-update"
init_end_mesasge chaîne identifies how many updates were installed and the URLS (for Windows) or names of the patches/updates

Pause Server

Sends the pause operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to pause a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the pause command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/pause

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/pause

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform pause operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power Off Server

Sends the power off operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power off a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power off command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOff

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOff

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform power off operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power On Server

Sends the power on operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power on a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power on command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOn

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOn

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform power on operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
array complex Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reboot Server

Sends the reboot operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reboot a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reboot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reboot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reboot

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform reboot operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reset Server

Sends the reset operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reset a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reset command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reset

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reset

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform reset operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Set Maintenance Mode

Sends a specified setting for maintenance mode per server to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly turn on or off maintenance mode on multiple servers. Specifically, this call can be used if you want set some servers to have maintenance mode on and others to have it off. If you want to set maintenance mode for servers to all on or all off, you can use the respective methods for starting maintenance mode or stopping maintenance mode for multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/setMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/setMaintenance

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
servers array List of server ID and maintenance mode pairs to set. Oui

Servers Definition

Name Type Description
id chaîne ID of server to set maintenance mode on or off
inMaintenanceMode boolean Indicator of whether to place server in maintenance mode or not

Examples

JSON

{
  "servers":[
    {
      "id": "wa1aliaswb01",
      "inMaintenanceMode": "true"
    },
    {
      "id": "wa1aliaswb02",
      "inMaintenanceMode": "false"
    }
  ]
}

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Shut Down Server

Sends the shut down operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to shut down a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the shut down command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/shutDown

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/shutDown

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform shut down operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Start Maintenance Mode

Sends a the start maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly start maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/startMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/startMaintenance

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to start maintenance mode on. Oui

Request Example

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Stop Maintenance Mode

Sends a the stop maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly stop maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/stopMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/stopMaintenance

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to stop maintenance mode on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Public IP: See Firewall

APIs for Public IP are located within the Firewall section.

.

.

Get Status

Gets the status of a particular job in the queue, which keeps track of any long-running asynchronous requests (such as server power operations or provisioning tasks). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to check the status of a specific job in the queue. It is usually called after running a batch job and receiving the job identifier from the status link (e.g. Power On Server, Create Server, etc.) and will typically continue to get called until a "succeeded" or "failed" response is returned.

URL

Structure

GET https://api.ctl.io/v2/operations/{accountAlias}/status/{statusId}

Example

GET https://api.ctl.io/v2/operations/ALIAS/status/wa1-12345

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui
Status ID chaîne ID of the job to query. Retrieved from the status link in the response to a batch job request. Oui

Réponse

Entity Definition

Name Type Description
État chaîne The status of the operation. Will be one of the following: "notStarted", "executing", "succeeded", "failed", "resumed" or "unknown".

Examples

JSON

{
  "status":"succeeded"
}

Create Subscription Backup Operation

Initiation a subscription backup's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a subscription's backup. You may restore a backup to the subscription it was created from, or to another subscription with equal or greater storage. Backup restore is an asynchronous process; valid requests will be accepted and the restore request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957/operations

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui
backupId nombre Backup id. Oui

Content Properties

Name Type Description Req.
type chaîne 'restore' Oui
toSubscriptionId nombre The id of the subscription you want to restore this backup to. The target subscription may be any subscription in your account that has equal or greater storage. Oui

Create Subscription Backup

Create a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to initiate a subscription backup. Backup creation is an asynchronous process; valid requests will be accepted and the create request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Create Subscription Notification Operation

Initiate a subscription notification's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to verify a subscription notification. You must provide the token sent in the notification verification email.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19/operations

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui
notificationId nombre Notification id. Oui

Content Properties

Name Type Description Req.
type chaîne 'verify' Oui
token chaîne Token included in the notification verification email. Oui

Create Subscription Notification

Create a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a subscription's notification. Subscriptions can be configured to notify users of high CPU or Storage use through Notifications. When a new notification is created, the recipient must validate their email through a url provided in a notification verification email before they begin to receive email notifications.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Content Properties

Name Type Description Req.
destinationType chaîne EMAIL. Oui
recipient chaîne Email address to send notificaitons to. Oui
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION. Oui

Réponse

Entity Definition

Name Type Description
id nombre Notification id.
destinationType chaîne EMAIL
recipient chaîne Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Create Subscription Operation

Initiate a subscription's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to failover a replicated subscription. Subscription failover is an asynchronous process; valid requests will be accepted and the failover request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/operations

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Content Properties

Name Type Description Req.
type chaîne 'failover' Oui

Create Subscription

Create a new subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new subscription.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
instanceType chaîne One of MYSQL, MySQL_REPLICATION Oui
emplacement chaîne Datacenter id. Available datacenters are listed in Get Datacenters method Oui
externalId chaîne The hostname part of the connection string Oui
machineConfig Objet Server provisioning information for cpu, memory, and storage Oui
backupRetentionDays nombre Number of days to retain database backups Oui
destinations array Server capacity notification destinations Non
users array Initial database user account. Oui
backupTime objet Time of day to run backups (UTC) Oui

MachineConfig Definition

Name Type Description Req.
cpu nombre Number of CPUs to allocate to server Oui
memory nombre Amount of RAM to allocate to server (GB) Oui
stockage nombre Amount of disk storage to allocate to server (GB) Oui

Destination Definition

Name Type Description Req.
destinationType chaîne EMAIL Oui
emplacement chaîne Where to send notifications. For EMAIL, this is an email address. Oui
notifications array A list of notifications to receive. Oui

User Definition

Name Type Description Req.
nom chaîne User name. Oui
password chaîne User password. The password must pass our minimum requirements: at least 9 characters and contain at least 3 of the following: uppercase letters, lowercase letters, numbers, symbols Oui

BackupTime Definition

Name Type Description Req.
hour nombre Hour of day to start backup (UTC). Oui
minute nombre Minute of minute to start backup (UTC). Oui

Example

{
  "instanceType": "MySQL",
  "location": "VA1",
  "externalId": "st-api-test",
  "machineConfig": {
    "cpu": 1,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 7,
  "destinations": [
    {
      "destinationType": "EMAIL",
      "location": "foo@bar.com",
      "notifications": [
        "CPU_UTILIZATION",
        "MEMORY_UTILIZATION"
      ]
    }
  ],
  "users": [
   {
     "name": "admin",
     "password": "AstrongPW!"
   }
  ],
  "backupTime": {
    "hour": 9,
    "minute": 15
  }
}

Réponse

Entity Definition

Name Type Description
id nombre Subscription id
emplacement chaîne Datacenter id
instanceType chaîne Type of relational database.
externalId chaîne External id used in connection strings, etc.
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown
backupTime chaîne Scheduled backup time in "hour:minute"
backupRetentionDays chaîne Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host chaîne Host DNS name used in connection strings.
port chaîne Host port used in connection strings.
certificate chaîne TLS certificate used to secure subscription connections.

Server Entity Definition

Name Type Description
id nombre Server id
alias chaîne Server alias (hostname)
emplacement chaîne Datacenter id where server is located
cpu nombre Number of CPUs allocated to the server
memory nombre Amount of RAM allocated to the server (GB)
stockage nombre Amount of disk storage allocated to the server (GB)
attributes objet Misc attributes for the server
connections nombre Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "9:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 1,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

Delete Subscription Backup

Delete a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription backup. Backup deletion is an asynchronous process; valid requests will be accepted and the delete request queued for further processing.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui
backupId nombre Backup id. Oui

Delete Subscription Notification

Delete a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription notification.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui
notificationId nombre Notification id. Oui

Delete Subscription

Delete an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
subscriptionId nombre Subscription id Oui

Get Billing

Returns current RDBS billing for an entire account or individual subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see current billing for the entire account or a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/billing?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/billing?subscriptionId=744

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Query Parameters

Name Type Description
subscriptionId nombre Subscription id to narrow billing focus to a single subscription. You can get a list of all subscriptions with Get Subscriptions API operation.

Réponse

Entity Definition

Name Type Description
productCode future future
metadata objet future
monthlyEstimate chaîne Estimate of monthly charge for this account or subscription.
monthToDate chaîne Monthly charges to date for this account or subscription.
currentHour chaîne Hourly charges for this account or subscription.

JSON

{
  "productCode": null,
  "metadata": {},
  "monthlyEstimate": "446,83 $",
  "monthToDate": "85,52 $",
  "currentHour": "0,60 $"
}

Get Datacenters

Get a list of datacenters providing RDBS subscriptions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to identify datacenters that you may create subscriptions in. You will use the dataCenter response attribute in create subscription requests.

URL

Example

GET https://api.rdbs.ctl.io/v1/datacenters

Réponse

Entity Definition

Name Type Description
dataCenter chaîne Short string representing the data center.
friendlyName chaîne Name of the datacenter.
active boolean Is the datacenter accepting new subscriptions.

JSON

[
  {
    "dataCenter": "UC1",
    "friendlyName": "UC1 - US West (Santa Clara)",
    "active": true
  },
  {
    "dataCenter": "VA1",
    "friendlyName": "VA1 - US East (Sterling)",
    "active": true
  }
]

Get History

Returns an ordered history of actions performed on all account subscriptions, or a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see actions performed on all subscriptions on an account, or actions performed on a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/history?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/history
GET https://api.rdbs.ctl.io/v1/ALIAS/history?subscriptionId=744

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui

Query Parameters

Name Type Description
subscriptionId nombre Subscription id to narrow focus to a single subscription. Subscription Ids are listed in the Get Subscriptions API operation.

Réponse

Entity Definition

Name Type Description
timestamp nombre Unix style timestamp; milliseconds since epoch.
message chaîne Summary message of form "subscription name: message".
details chaîne Additional details, if available.
user chaîne User initiating the action. An RDBS service account is listed when the action is provided by the service, like automated failover to replicated instances.

JSON

[
  {
    "timestamp": 1459878501968,
    "message": "demo-dev: created.",
    "details": "1 CPU, 1GB RAM, 1GB storage",
    "user": "user1"
  },
  {
    "timestamp": 1459878122697,
    "message": "poc1-test: deleted.",
    "details": null,
    "user": "user2"
  },
  {
    "timestamp": 1459455272384,
    "message": "config-db: failed over (automatic).",
    "details": "Primary server became active.",
    "user": "dbaas_service"
  },
  ...
]

Get Promotions

Returns all promotions applied to this account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all promotions applied to an account.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/promotions

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/promotions

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui

Réponse

Entity Definition

Name Type Description
code chaîne Promotion code.

JSON

{
  "code": "PROMO_2016"
}

Get Subscription Backups

Returns details of subscription backups. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's backups.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Réponse

Entity Definition

Name Type Description
id nombre Backup id.
fileName chaîne Backup file name.
backupTime nombre Unix timestamp of milliseconds since epoch.
backupType chaîne One of Automated, Manual .
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size nombre Size of the compressed backup.

JSON

[
  {
    "id": 2656,
    "fileName": "UC1DBDVMYSQL566-2016-04-06_23-00-01.tar.gz",
    "backupTime": 1459983603000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842348
  },
  {
    "id": 2674,
    "fileName": "UC1DBDVMYSQL566-2016-04-07_23-00-01.tar.gz",
    "backupTime": 1460070003000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842335
  },
  ...
}

Get Subscription Certificate

Returns the subscription TLS certificate as a stream. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to download a subscription certificate. Subscription certificates are included in the Get Subscription API operation; this API operation downloads the certificate as a file.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/certificate

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/certificate

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Réponse

Entity Definition

Name Type Description
N/A octet stream The certificate is returned as application/octet-stream with a default name of <subscription.externalId>.pem

Get Subscription Notifications

Returns all subscription notifications. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's notifications.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Réponse

Entity Definition

Name Type Description
id nombre Notification id.
destinationType chaîne EMAIL
recipient chaîne Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Get Subscription

Returns details of a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a single subscription's details.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Réponse

Entity Definition

Name Type Description
id nombre Subscription id.
emplacement chaîne Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType chaîne Type of relational database.
externalId chaîne External id used in connection strings, etc.
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime chaîne Scheduled backup time in "hour:minute".
backupRetentionDays chaîne Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host chaîne Host DNS name used in connection strings.
port chaîne Host port used in connection strings.
certificate chaîne TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id nombre Server id.
alias chaîne Server alias (hostname).
emplacement chaîne Datacenter id where server is located.
cpu nombre Number of CPUs allocated to the server.
memory nombre Amount of RAM allocated to the server (GB).
stockage nombre Amount of disk storage allocated to the server (GB).
attributes objet Misc attributes for the server.
connections nombre Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type Description
id nombre Backup id.
fileName chaîne Backup file name.
backupTime nombre Unix timestamp of milliseconds since epoch.
backupType chaîne One of Automated, Manual .
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size nombre Size of the compressed backup.

JSON

{
"id": 2957,
"location": "IL1",
"instanceType": "MySQL",
"externalId": "config-db",
"status": "Active",
"backupTime": "0:0",
"backupRetentionDays": 7,
"servers": [
  {
    "id": 2917,
    "alias": "IL1DBPDMYSQLXXXX",
    "location": "IL1",
    "cpu": 1,
    "memory": 1,
    "storage": 1,
    "attributes": {
      "INTERNAL_IP": "10.90.85.43"
    },
    "connections": 89
  }
],
"host": "config-db.il1.rdbs.ctl.io",
"port": 49929,
"certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
"backups": [
  {
    "id": 27538,
    "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
    "backupTime": 1459296004000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2841295
  },
  ...
}

Get Subscriptions

Returns a list of all subscriptions and details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all subscriptions and their details. You can narrow focus to a single datacenter and/or subscription status.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions?dataCenter={dataCenterId}&status={status}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?staus=ACTIVE
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1&staus=PENDING

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account. Oui

Query Parameters

Name Type Description
dataCenter chaîne Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation
status chaîne One of: ACTIVE, BACKING_UP, CONFIGURING, DELETED, FAILED, PENDING, READY, RESTORING, SUCCESS, TERMINATED, UNKNOWN

Réponse

Entity Definition

Name Type Description
id nombre Subscription id.
emplacement chaîne Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType chaîne Type of relational database.
externalId chaîne External id used in connection strings, etc.
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime chaîne Scheduled backup time in "hour:minute".
backupRetentionDays chaîne Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host chaîne Host DNS name used in connection strings.
port chaîne Host port used in connection strings.
certificate chaîne TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id nombre Server id.
alias chaîne Server alias (hostname).
emplacement chaîne Datacenter id where server is located.
cpu nombre Number of CPUs allocated to the server.
memory nombre Amount of RAM allocated to the server (GB).
stockage nombre Amount of disk storage allocated to the server (GB).
attributes objet Misc attributes for the server.
connections nombre Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type Description
id nombre Backup id.
fileName chaîne Backup file name.
backupTime nombre Unix timestamp of milliseconds since epoch.
backupType chaîne One of Automated, Manual.
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size nombre Size of the compressed backup.

JSON

[
  {
    "id": 2957,
    "location": "IL1",
    "instanceType": "MySQL",
    "externalId": "config-db",
    "status": "Active",
    "backupTime": "0:0",
    "backupRetentionDays": 7,
    "servers": [
      {
        "id": 2917,
        "alias": "IL1DBPDMYSQLXXXX",
        "location": "IL1",
        "cpu": 1,
        "memory": 1,
        "storage": 1,
        "attributes": {
          "INTERNAL_IP": "10.90.85.43"
        },
        "connections": 89
      }
    ],
    "host": "config-db.il1.rdbs.ctl.io",
    "port": 49929,
    "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
    "backups": [
      {
        "id": 27538,
        "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
        "backupTime": 1459296004000,
        "backupType": "Automated",
        "status": "SUCCESS",
        "size": 2841295
      },
      ...
    ]
  },
  ...

Patch Subscription

Modify an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to resize a subscription server(s), change the number of days to keep backups, or the backup time.

NOTE: A subscription storage allocation cannot be reduced.

URL

Structure

PATCH https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

PATCH https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui

Content Properties

Name Type Description Req.
machineConfig Objet Server provisioning information for cpu, memory, and storage. Oui
backupRetentionDays nombre Number of days to retain database backups. Oui
backupTime objet Time of day to run backups (UTC). Oui

MachineConfig Definition

Name Type Description Req.
cpu nombre Number of CPUs to allocate to server. Oui
memory nombre Amount of RAM to allocate to server (GB). Oui
stockage nombre Amount of disk storage to allocate to server (GB). Oui

BackupTime Definition

Name Type Description Req.
hour nombre Hour of day to start backup (UTC). Oui
minute nombre Minute of minute to start backup (UTC). Oui

Example

{
  "machineConfig": {
    "cpu": 2,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 6,
  "backupTime": {
    "hour": 1,
    "minute": 15
  }
}

Réponse

Entity Definition

Name Type Description
id nombre Subscription id.
emplacement chaîne Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType chaîne Type of relational database.
externalId chaîne External id used in connection strings, etc.
status chaîne One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime chaîne Scheduled backup time in "hour:minute".
backupRetentionDays chaîne Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host chaîne Host DNS name used in connection strings.
port chaîne Host port used in connection strings.
certificate chaîne TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id nombre Server id.
alias chaîne Server alias (hostname).
emplacement chaîne Datacenter id where server is located.
cpu nombre Number of CPUs allocated to the server.
memory nombre Amount of RAM allocated to the server (GB).
stockage nombre Amount of disk storage allocated to the server (GB).
attributes objet Misc attributes for the server.
connections nombre Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "1:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 2,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

Commencer

The Relational DataBase Services (RDBS) API focuses on manipulating Subscriptions to the RDBS service. A Subscription includes the backing database server(s), certificates, database backups, and notifications.

You can also view RDBS billing, action history, and promotions applied to your account.

The RDBS api is a satellite of the platform API and offered on a separate URL.

Base URL: https://api.rdbs.ctl.io/v1/

Update Subscription Notification

Update a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change a subscription notification.

URL

Structure

PUT https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

PUT https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account. Oui
subscriptionId nombre Subscription id. Oui
notificationId nombre Notification id. Oui

Content Properties

Name Type Description Req.
destinationType chaîne EMAIL. Oui
recipient chaîne Email address to send notificaitons to. Oui
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION. Oui

Réponse

Entity Definition

Name Type Description
id nombre Notification id.
destinationType chaîne EMAIL
recipient chaîne Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Add Secondary Network

Adds a secondary network adapter to a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to add a secondary network adapter to a server. You will need a NetworkId to associate with the server. Users have the option to specify an IP address to assign to the server; otherwise the first available IP address in the network will be assigned. Up to four total network adapters can be attached to a server (i.e. a total of 3 secondary adapters). In addition, only one IP address per secondary network can be associated with a server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks

Requête

URI Parameters

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server Oui

Content Properties

Name Type Description Req.
networkId chaîne ID of the network. These can be retrieved from the Get Network List API operation Oui
ipAddress chaîne Optional IP address for the networkId Non

Examples

JSON

{
      "networkId": "61a7e67908ce4bedabfdaf694a1360fe",
      "ipAddress": "123.456.1.1"
}

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be available on the server.

Entity Definition

Name Type Description
operationId chaîne GUID for the item in the queue for completion
uri chaîne Link to review status of the operation

Examples

JSON

  {
    "operationId": "2b70710dba4142dcaf3ab2de68e4f40c",
    "uri": "http://api.ctl.io/v2-experimental/operations/RSDA/status/2b70710dba4142dcaf3ab2de68e4f40c"
  }

Clone Server

Creates a new server as a clone of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

Requête

The request parameters are the same as defined for Create Server with the addition of the sourceServerPassword parameter being required when cloning a server. Also, note that the sourceServerId parameter should be the name of the server that is being cloned rather than a template name.

Examples

JSON

{
  "name": "web",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "WA1ALIASWEB01",
  "sourceServerPassword": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard"
}

Réponse

The response will be the same as specified in Create Server.

Create Server

Creates a new server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-8 characters depending on the length of the account alias. The combination of account alias and server name here must be no more than 10 characters in length. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.) Oui
description chaîne User-defined description of this server Non
groupId chaîne ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Oui
sourceServerId chaîne ID of the server to use a source. May be the ID of a template, or when cloning, an existing server ID. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.) Oui
isManagedOS bool Whether to create the server as managed or not. Default is false. (Ignored for bare metal servers.) Non
isManagedBackup bool Whether to add managed backup to the server. Must be a managed OS server. (Ignored for bare metal servers.) Non
primaryDns chaîne Primary DNS to set on the server. If not supplied the default value set on the account will be used. Non
secondaryDns chaîne Secondary DNS to set on the server. If not supplied the default value set on the account will be used. Non
networkId chaîne ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. Non
ipAddress chaîne IP address to assign to the server. If not provided, one will be assigned automatically. (Ignored for bare metal servers.) Non
password chaîne Password of administrator or root user on server. If not provided, one will be generated automatically. Non
sourceServerPassword chaîne Password of the source server, used only when creating a clone from an existing server. (Ignored for bare metal servers.) Non
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers) Oui
cpuAutoscalePolicyId chaîne ID of the vertical CPU Autoscale policy to associate the server with. Available IDs can be retrieved from the Get Autoscale Policies API operation. (Ignored for bare metal servers.) Non
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers) Oui
type chaîne Whether to create a standard, hyperscale, or bareMetal server Oui
antiAffinityPolicyId chaîne ID of the Anti-Affinity policy to associate the server with. Only valid for hyperscale servers. Available IDs can be retrieved from the Get Anti-Affinity Policies API operation. Non
customFields complex Collection of custom field ID-value pairs to set for the server. Non
additionalDisks complex Collection of disk parameters (ignored for bare metal servers) Non
ttl dateTime Date/time that the server should be deleted (ignored for bare metal servers) Non
packages complex Collection of packages to run on the server after it has been built (ignored for bare metal servers) Non
configurationId chaîne Only required for bare metal servers. Specifies the identifier for the specific configuration type of bare metal server to deploy. A list of possible configs can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.) Oui
osType chaîne Only required for bare metal servers. Specifies the OS to provision with the bare metal server. Currently, the only supported OS types are redHat6_64Bit, centOS6_64Bit, windows2012R2Standard_64Bit, windows2012R2Datacenter_64Bit, ubuntu14_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.) Oui

CustomFields Definition

Name Type Description
id chaîne ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value chaîne Value to set the custom field to for this server.

AdditionalDisks Definition

Name Type Description
path chaîne File system path for disk (Windows drive letter or Linux mount point). Must not be one of reserved names.
sizeGB integer Amount in GB to allocate for disk, up to 1024 GB per.
type chaîne Whether the disk should be raw or partitioned

Packages Definition

Name Type Description
packageId chaîne ID of the package to run on the server after it builds. Available package IDs can be retrieved from the Get Packages API operation.
parameters complex Collection of name-value pairs to specify package-specific parameters.

Examples

JSON

{
  "name": "web",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "RHEL-6-64-TEMPLATE",
  "isManagedOS": false,
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "ipAddress": "10.123.456.12",
  "password": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "additionalDisks":[
    {
      "path": "data",
      "sizeGB": 10,
      "type": "partitioned"
    }
  ],
  "ttl": "2014-12-17T01:17:17Z"
}

Réponse

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"web",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Delete Server

Sends the delete operation to a given server and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a server that is no longer being used.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTWB01

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server to be deleted. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Réponse

Entity Definition

Name Type Description
serveur chaîne ID of the server that is being deleted.
isQueued boolean Boolean indicating whether the delete operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"wa1acctwb01",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Get Available Server Imports

Gets the list of available servers that can be imported. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the list of available OVFs that can be imported with the Import Server API. These OVFs are ones that have been uploaded to your FTP server as described in Using Self-Service VM Import.

URL

Structure

GET https://api.ctl.io/v2/vmImport/{accountAlias}/{locationId}/available

Example

GET https://api.ctl.io/v2/vmImport/ALIAS/WA1/available

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
LocationId chaîne Data center location identifier Oui

Réponse

The response is an array of available servers for import. The list of available servers is dependent upon what OVFs have been uploaded to your FTP server as described in Using Self-Service VM Import.

Entity Definition

Name Type Description
id chaîne ID of the OVF.
nom chaîne Name of the OVF.
storageSizeGB integer Number of GB of storage the server is configured with.
cpuCount integer Number of processors the server is configured with.
memorySizeMB integer Number of MB of memory the server is configured with.

Examples

JSON

[
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT",
    "name":"CUSTOM-OVF-IMPORT-RHEL-6-64",
    "storageSizeGB":16,
    "cpuCount":1,
    "memorySizeMB":1024
  },
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT-2",
    "name":"CUSTOM-OVF-IMPORT-2",
    "storageSizeGB":60,
    "cpuCount":2,
    "memorySizeMB":4096
  }
]

Get Server Credentials

Retrieves the administrator/root password on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the administrator/root password for an existing server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/credentials

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/credentials

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the credentials to return. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Réponse

Entity Definition

Name Type Description
userName chaîne The username of root/administrator on the server. Typically "root" for Linux machines and "Administrator" for Windows.
password chaîne The administrator/root password used to login.

Examples

JSON

{
  "userName":"root",
  "password":"P@ssw0rd1"
}

Get Server

Gets the details for a individual server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out all the details for a server. It can be used to look for changes, its status, or to retrieve links to associated resources.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Réponse

Server Entity Definition

Name Type Description
id chaîne ID of the server being queried
nom chaîne Name of the server
displayName chaîne Friendly display name for the server (can be the same as the name)
description chaîne User-defined description of this server
groupId chaîne ID of the parent group
isTemplate boolean Boolean indicating whether this is a custom template or running server
locationId chaîne Data center that this server resides in
osType chaîne Friendly name of the Operating System the server is running
isManagedOS boolean Describes whether the server is managed or not. Only appears when the server is managed.
isManagedBackup boolean Describes whether the server has Managed Backup or not. Only appears when the server has both Managed OS and Managed Backup.
status chaîne Describes whether the server is active or not
details complex Managed applications, resource allocations, alert policies, snapshots and more.
type chaîne Whether a standard or premium server
storageType chaîne Whether it uses standard or premium storage
changeInfo complex Describes "created" and "modified" details
links array Collection of entity links that point to resources related to this server

Details Definition

Name Type Description
ipAddresses complex Details about IP addresses associated with the server
alertPolicies complex Describe each alert policy applied to the server
cpu integer How many vCPUs are allocated to the server
diskCount integer How many disks are attached to the server
hostName chaîne Fully qualified name of the server
inMaintenanceMode boolean Indicator of whether server has been placed in maintenance mode
memoryMB integer How many MB of memory are allocated to the server
powerState chaîne Whether the server is running or not
storageGB integer How many total GB of storage are allocated to the server
disks complex The disks attached to the server
partitions complex The partitions defined for the server
instantanés complex Details about any snapshot associated with the server
customFields complex Details about any custom fields and their values
processorDescription chaîne Processor configuration description (for bare metal servers only)
storageDescription chaîne Storage configuration description (for bare metal servers only)

IPAddresses Definition

Name Type Description
public chaîne If applicable, the public IP
internal chaîne Private IP address. If associated with a public IP address, then the "public" value is populated

AlertPolicies Definition

Name Type Description
id chaîne Unique identifier of the policy
nom chaîne User-defined name of the alert policy
links array Collection of entity links that point to resources related to this policy

Disks Definition

Name Type Description
id chaîne Unique identifier of the disk
sizeGB integer Size of the disk in GB
partitionPaths array List of partition paths on the disk

Partitions Definition

Name Type Description
sizeGB nombre Size of the partition in GB
path chaîne File system location path of the partition

Snapshots Definition

Name Type Description
nom chaîne Timestamp of the snapshot
links array Collection of entity links that point to resources related to this snapshot

CustomFields Definition

Name Type Description
id chaîne Unique ID of the custom field
nom chaîne Friendly name of the custom field
value chaîne Underlying value of the field
displayValue chaîne Shown value of the field

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the server was created
createdBy chaîne Who created the server
modifiedDate dateTime Date/time that the server was last updated
modifiedBy chaîne Who modified the server last

Examples

JSON

{
  "id": "WA1ALIASWB01",
  "name": "WA1ALIASWB01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.82.131.44"
      },
      {
        "public": "91.14.111.101",
        "internal": "10.82.131.45"
      }
    ],
    "alertPolicies": [
      {
        "id": "15836e6219e84ac736d01d4e571bb950",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/15836e6219e84ac736d01d4e571bb950"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/15836e6219e84ac736d01d4e571bb950",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      },
      {
        "id": "2bec81dd90aa4217887548c3c20d7421",
        "name": "Production Web Servers - Disk",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/2bec81dd90aa4217887548c3c20d7421"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/2bec81dd90aa4217887548c3c20d7421",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 2,
    "diskCount": 1,
    "hostName": "WA1ALIASWB01.customdomain.com",
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 60,
    "disks":[
      {
        "id":"0:0",
        "sizeGB":60,
        "partitionPaths":[]
      }
    ],
    "partitions":[
      {
        "sizeGB":59.654,
        "path":"C:\\"
      }
    ],
    "snapshots": [
      {
        "name": "2014-05-16.23:45:52",
        "links": [
          {
            "rel": "self",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "delete",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "restore",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40/restore"
          }
        ]
      }
    ],
    "customFields": [
      {
        "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": "58f83af6123846769ee6cb091ce3561e",
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/alias/WA1ALIASWB01",
      "id": "WA1ALIASWB01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/alias/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/alias",
      "id": "alias"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/alias/estimate-server/WA1ALIASWB01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/alias/WA1ALIASWB01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/alias/WA1ALIASWB01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/alias/WA1ALIASWB01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/alias/WA1ALIASWB01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses/91.14.111.101",
      "id": "91.14.111.101",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

Import Server

Imports a new server from an uploaded OVF. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to import a new server from an OVF that has been uploaded to your FTP server. For more information about uploading an OVF for import, see Using Self-Service VM Import and make sure the OVF meets these requirements before attempting to import it.

URL

Structure

POST https://api.ctl.io/v2/vmImport/{accountAlias}

Example

POST https://api.ctl.io/v2/vmImport/ALIAS/

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
nom chaîne Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-7 characters depending on the length of the account alias. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.) Oui
description chaîne User-defined description of this server Non
groupId chaîne ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Oui
primaryDns chaîne Primary DNS to set on the server. If not supplied the default value set on the account will be used. Non
secondaryDns chaîne Secondary DNS to set on the server. If not supplied the default value set on the account will be used. Non
networkId chaîne ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. Non
password chaîne Password of administrator or root user on server. This password must match the one set on the server being imported or the import will fail. Oui
cpu integer Number of processors to configure the server with (1-16). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here. Oui
memoryGB integer Number of GB of memory to configure the server with (1-128). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here. Oui
type chaîne Whether to create standard or hyperscale server Oui
customFields complex Collection of custom field ID-value pairs to set for the server. Non
ovfId chaîne The identifier of the OVF that defines the server to import. This can be retrieved from the Get Available Server Imports API operation.
ovfOsType chaîne The OS type of the server being imported. Currently, the only supported OS types are redHat6_64Bit, windows2008R2DataCenter_64bit, and windows2012R2DataCenter_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Deployment Capabilities API operation.

CustomFields Definition

Name Type Description
id chaîne ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value chaîne Value to set the custom field to for this server.

Examples

JSON

{
  "name": "import",
  "description": "Custom Import Server",
  "groupId": "3d30a6bc6b5443388b7bc966d073e353",
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "password": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "ovfId": "ALIAS/CUSTOM-OVF-IMPORT",
  "ovfOsType": "redHat6_64Bit"
}

Réponse

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"import",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Remove Secondary Network

Removes a secondary network adapter from a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to remove a secondary network adapter from a server. You will need a NetworkId to de-associate with the server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks/{networkId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks/f49875b17cee4b8c99bf1ab75aa286d6

Requête

URI Properties

Name Type Description Req.
accountAlias chaîne Short code for a particular account Oui
serverId chaîne ID of the server Oui
networkId chaîne ID of the network. These can be retrieved from the Get Network List API operation Oui

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be removed from the server.

Entity Definition

Name Type Description
operationId chaîne GUID for the item in the queue for completion
uri chaîne Link to review status of the operation

Examples

JSON

  {
    "operationId": "6c8d7b5349054fe6a532539ff066b53b",
    "uri": "http://api.ctl.io/v2-experimental/operations/ALIAS/status/6c8d7b5349054fe6a532539ff066b53b"
  }

Set Server CPU/Memory

Changes the amount of CPU cores and memory (in GB) on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the number of CPU cores or the amount of memory for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the CPU or memory configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the server. In this case, the value must be "set" for setting the CPU or memory amount.
member chaîne The property of the server to perform the operation on. In this case, the value will be either "cpu" or "memory".
value integer The integer value to set for the given member. For CPU this represents the number of cores; for memory it is in GB.

Examples

JSON

[
   {
      "op":"set",
      "member":"cpu",
      "value":"4"
   },
   {
      "op":"set",
      "member":"memory",
      "value":"8"
   }
]

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Credentials

Changes the administrator/root password on an existing server given the current administrator/root password. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the administrator/root password on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the credentials to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the server. In this case, the value must be "set" for setting the credentials.
member chaîne The property of the server to perform the operation on. In this case, the value must be "password" for setting the credentials.
value complex The current and new administrator/root password values.

Value Definition

Name Type Description
current chaîne The current administrator/root password used to login.
password chaîne The new administrator/root password to change to.

Examples

JSON

[
   {
      "op":"set",
      "member":"password",
      "value":
      {
         "current":"OldP@ssw0rd1",
         "password":"NewP@ssw0rd2"
      }
   }
]

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the password will be changed as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Custom Fields

Changes the custom field values for an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the server. In this case, the value must be "set" for setting the custom field values.
member chaîne The property of the server to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the server. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Server call to see all the details of the server or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Description/Group

Changes the description and parent group of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the description or the parent group of a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the server. In this case, the value must be "set" for setting the description and parent group.
member chaîne The property of the server to perform the operation on. In this case, the value will be either "description" or "groupId".
value chaîne The value to set for the given member. This is either the description of the server to set, or the unique identifier of the group to set as the parent.

Examples

JSON

[
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   },
   {
      "op":"set",
      "member":"groupId",
      "value":"2a5c0b9662cf4fc8bf6180f139facdc0"
   }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Disks

Changes (adds or removes) disks on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the disks on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the disk configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Oui

PatchOperation Definition

Name Type Description
op chaîne The operation to perform on a given property of the server. In this case, the value must be "set" for setting the disk configuration.
member chaîne The property of the server to perform the operation on. In this case, the value must be "disks" for setting the disks.
value array A list of information for all disks to be on the server including type (raw or partition), size, and path.

Note: You must specify the complete list of disks to be on the server. If you want to add or resize a disk, specify all existing disks/sizes along with a new entry for the disk to add or the new size of an existing disk. To delete a disk, just specify all the disks that should remain. (You can get existing disk info by using the Get Server call to see all the details of the server.)

Examples

JSON

[
  {
    "op":"set",
    "member":"disks",
    "value":[
      {
        "diskId":"0:0",
        "sizeGB":"1",
        "type":"raw"
      },
      {
        "diskId":"0:1",
        "sizeGB":"2",
        "type":"raw"
      },
      {
        "diskId":"0:2",
        "sizeGB":"16",
        "type":"raw"
      },
      {
        "path":"/extra",
        "sizeGB":"20",
        "type":"partitioned"
      }
    ]  
  }
]

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Archive Server

Sends the archive operation to a list of servers and adds operation to queue. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the archive command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/archive

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/archive

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform archive operation on. Oui

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Création d'une copie instantanée

Sends the create snapshot operation to a list of servers (along with the number of days to keep the snapshot for) and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a snapshot of a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the create snapshot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/createSnapshot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/createSnapshot

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
snapshotExpirationDays integer Number of days to keep the snapshot for (must be between 1 and 10). Oui
serverIds array List of server names to perform create snapshot operation on. Oui

Examples

JSON

{
  "snapshotExpirationDays":"7",
  "serverIds":[
      "WA1ALIASWB01",
      "WA1ALIASWB02"
    ]
}

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Suppression d'une copie instantanée

Deletes a given server snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing server snapshot.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the snapshot to delete. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui
SnapshotId chaîne ID of the snapshot to delete. Retrieved from the links in the snapshots section of the Get Server response.

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Execute Package

Executes a single package on one or more servers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to execute a Blueprint package that is available from within a given account on one or more servers. The list of available packages can be retrieved from the Get Packages API operation.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/executePackage

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/executePackage

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Content Properties

Name Type Description Req.
servers array List of server IDs to run the package on. Oui
package complex The package entity describing which package to run on the specified servers. Oui

Package Definition

Name Type Description
packageId chaîne Unique identifier of the package to execute.
parameters complex Set of key-value pairs for setting the package-specific parameters defined.

Examples

JSON

{
    "servers": [
        "wa1aliaswb01"
    ],
    "package": {
        "packageId": "86567681-c79c-1234-a530-850708435c23",
        "parameters": {
            "AB.HelloWorld.Variable": "someValue"
        }
    }
}

Réponse

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
serveur chaîne ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage chaîne If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  }
]

Restore Server

Restores a given archived server to a specified group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a server that has been archived.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/restore

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/restore

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the archived server to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui

Content Properties

Name Type Description Req.
targetGroupId chaîne The unique identifier of the target group to restore the server to. Oui

Examples

JSON

{
  "targetGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0"
}

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server will be restored as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Revert to Snapshot

Reverts a server to a snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to revert a server to the state it was in when the given snapshot was taken.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}/restore

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10/restore

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
ServerId chaîne ID of the server with the snapshot to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Oui
SnapshotId chaîne ID of the snapshot to restore. Retrieved from the links in the snapshots section of the Get Server response.

Réponse

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value Description
rel chaîne status The link type
href chaîne /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id chaîne [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create Load Balancer Pool

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancers in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui

Content Properties

Name Type Description Req.
port integer Port to configure on the public-facing side of the load balancer pool. Must be either 80 (HTTP) or 443 (HTTPS). Oui
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. Default is roundRobin. See Shared Load Balancer Overview for more information about these options. Non
persistence chaîne The persistence method for this load balancer, either standard or sticky. Default is standard. See Shared Load Balancer Overview for more information about these options. Non

Examples

JSON

{
	"port": 80,
	"method": "leastConnection",
  "persistence": "sticky"
}

Réponse

The response will be an entity representing the new load balancer pool that was created.

Entity Definition

Name Type Description
id chaîne ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Empty array since no nodes will be configured yet for the new pool
links array Collection of entity links that point to resources related to this load balancer pool

Examples

JSON

{
  "id" : "40150dde098640e8b993de0e7417afc4",
  "port" : 80,
  "method" : "leastConnection",
  "persistence" : "sticky",
  "nodes" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Create Shared Load Balancer

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancer in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Content Properties

Name Type Description Req.
nom chaîne Friendly name for new the load balancer Oui
description chaîne Description for new the load balancer Oui
status chaîne Status to create the load balancer with: enabled or disabled Non

Examples

JSON

{
	"name":"New Load Balancer",
	"description":"A brand new load balancer"
}

Réponse

The response will be an entity representing the new load balancer that was created.

Entity Definition

Name Type Description
id chaîne ID of the load balancer
nom chaîne Friendly name of the load balancer
description chaîne Description for the load balancer
ipAddress chaîne The external (public) IP address of the load balancer
status chaîne Status of the load balancer: enabled, disabled or deleted
pools array Empty array since no pools will be configured yet for the new shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Examples

JSON

{
  "id" : "6b66b474fce940b8b581242709b5b2f0",
  "name" : "New Load Balancer",
  "description" : "A brand new load balancer",
  "ipAddress" : "98.76.54.32",
  "status" : "enabled",
  "pools" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ],
}

Delete Load Balancer Pool

Deletes a given pool of a shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific pool from a given load balancer.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer with the pool to delete. Oui
PoolId chaîne ID of the pool to delete. Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Delete Shared Load Balancer

Deletes a given shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific load balancer within a given account and data center.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer to delete. Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Get Load Balancer Nodes

Gets the list of nodes configured behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of nodes configured behind a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui
PoolId chaîne ID of the pool containing the nodes Oui

Réponse

Entity Definition

The response will be an array containing one entity for each node configured.

Name Type Description
status chaîne Status of the node: enabled, disabled or deleted.
ipAddress chaîne The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.13",
    "privatePort" : 80
  },
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.14",
    "privatePort" : 80
  }
]

Get Load Balancer Pool

Gets a specified pool configured for the given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the details for a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui
PoolId chaîne ID of the pool Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
nom chaîne Name of the node (generally the IP address)
status chaîne Status of the node: enabled, disabled or deleted.
ipAddress chaîne The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "2fa937bd20dd47c9b856376e9499c0c1",
  "port" : 80,
  "method" : "roundRobin",
  "persistence" : "standard",
  "nodes" : [
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.13",
      "privatePort" : 80,
      "name" : "10.11.12.13"
    },
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.14",
      "privatePort" : 80,
      "name" : "10.11.12.14"
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Get Load Balancer Pools

Gets the list of pools configured for a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of pools configured for a given shared load balancer.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui

Réponse

Entity Definition

The response will be an array containing one entity for each pool configured on the given load balancer.

Name Type Description
id chaîne ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
nom chaîne Name of the node (generally the IP address)
status chaîne Status of the node: enabled, disabled or deleted.
ipAddress chaîne The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "2fa937bd20dd47c9b856376e9499c0c1",
    "port" : 80,
    "method" : "roundRobin",
    "persistence" : "standard",
    "nodes" : [
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.13",
        "privatePort" : 80,
        "name" : "10.11.12.13"
      },
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.14",
        "privatePort" : 80,
        "name" : "10.11.12.14"
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "nodes",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
        "verbs" : [
          "GET",
          "PUT"
        ]
      }
    ]
  }
]

Get Shared Load Balancer

Gets the specified shared load balancer for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a specific shared load balancer configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui

Réponse

Entity Definition

Name Type Description
id chaîne ID of the load balancer
nom chaîne Friendly name of the load balancer
description chaîne Description for the load balancer
ipAddress chaîne The external (public) IP address of the load balancer
status chaîne Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type Description
id chaîne ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
nom chaîne Name of the node (generally the IP address)
status chaîne Status of the node: enabled, disabled or deleted.
ipAddress chaîne The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "ae3bbac5d9694c70ad7de062476ccb70",
  "name" : "My Load Balancer",
  "description" : "My Load Balancer",
  "ipAddress" : "12.34.56.78",
  "status" : "disabled",
  "pools" : [
    {
      "id" : "2fa937bd20dd47c9b856376e9499c0c1",
      "port" : 80,
      "method" : "roundRobin",
      "persistence" : "standard",
      "nodes" : [
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.13",
          "privatePort" : 80,
          "name" : "10.11.12.13"
        },
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.14",
          "privatePort" : 80,
          "name" : "10.11.12.14"
        }
      ],
      "links" : [
        {
          "rel" : "self",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
          "verbs" : [
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel" : "nodes",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
          "verbs" : [
            "GET",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ]
}

Get Shared Load Balancers

Gets the list of shared load balancers that exist for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the list of shared load balancers configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui

Réponse

The response will be an array containing one entity for each load balancer in the given account and data center.

Entity Definition

Name Type Description
id chaîne ID of the load balancer
nom chaîne Friendly name of the load balancer
description chaîne Description for the load balancer
ipAddress chaîne The external (public) IP address of the load balancer
status chaîne Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type Description
id chaîne ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
nom chaîne Name of the node (generally the IP address)
status chaîne Status of the node: enabled, disabled or deleted.
ipAddress chaîne The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "ae3bbac5d9694c70ad7de062476ccb70",
    "name" : "My Load Balancer",
    "description" : "My Load Balancer",
    "ipAddress" : "12.34.56.78",
    "status" : "disabled",
    "pools" : [
      {
        "id" : "2fa937bd20dd47c9b856376e9499c0c1",
        "port" : 80,
        "method" : "roundRobin",
        "persistence" : "standard",
        "nodes" : [
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.13",
            "privatePort" : 80,
            "name" : "10.11.12.13"
          },
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.14",
            "privatePort" : 80,
            "name" : "10.11.12.14"
          }
        ],
        "links" : [
          {
            "rel" : "self",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
            "verbs" : [
              "GET",
              "PUT",
              "DELETE"
            ]
          },
          {
            "rel" : "nodes",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
            "verbs" : [
              "GET",
              "PUT"
            ]
          }
        ]
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "pools",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
        "verbs" : [
          "GET",
          "POST"
        ]
      }
    ]
  }
]

Shared Load Balancers Overview

Équilibreur de charge

A shared load balancer is made up of a VIP (virtual IP) and a set of servers grouped by pools (i.e. access ports). The load balancer entity is merely a named container with an IP address that can further be configured to include multiple pools of servers behind the same IP.

Load Balancer Pool

Within a shared load balancer definition, multiple pools can be configured. Each pool defines the port that will respond to and redirect traffic to the server nodes in the pool. The pool is also where the load balancing method and persistence types are set.

The method can either be set to "round robin" or "least connection." For the round robin option, the load balancer cycles through a list of all the servers bound to it. It does not take into account server workload or latency and simply distributes traffic evenly across servers. The least connection option routes traffic to the server with the fewest active connections. An "active" connection is considered one where the HTTP request has not yet received a response. This is considered the best performing of the two algorithms.

The persistence type can be either "standard" or "sticky." The standard option employs no persistence and is best for stateless web applications. If an application does require server-based state, then choose the sticky option. The sticky choice uses source IP + destination IP address-based persistence to tie users to the target server.

If you choose round robin or least connection along with standard persistence, then requests are routed without any concern for where the last user's request came from. If you choose round robin or least connection along with sticky persistence, then the FIRST request will be routed based on either round robin or least connection, and each subsequent request from that source IP address will return to the server that responded to the initial request.

Load Balancer Node

For each pool, one or more nodes are configured corresponding to a server that is included in the load balancing pool. The node definition includes the server's private IP address and the port that is serving the content.

Update Load Balancer Nodes

Updates the nodes behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the list of nodes in a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui
PoolId chaîne ID of the pool to update Oui

Content Properties

The body of the request is an array of node entities.

Name Type Description Req.
status chaîne Status of the node: enabled, disabled or deleted. Non
ipAddress chaîne The internal (private) IP address of the node server Oui
privatePort integer The internal (private) port of the node server. Must be a value between 1 and 65535. Oui

Examples

JSON

[
  {
    "ipAddress" : "10.11.12.18",
    "privatePort" : 8080
  },
  {
    "ipAddress" : "10.11.12.19",
    "privatePort" : 8080
  }
]

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the list of load balancer nodes.

Update Load Balancer Pool

Updates a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the port, method, or persistence options for a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer Oui
PoolId chaîne ID of the pool to update Oui

Content Properties

Name Type Description Req.
method chaîne The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options. Non
persistence chaîne The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options. Non

Examples

JSON

{
    "method": "roundRobin",
  "persistence": "standard"
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer pool.

Update Shared Load Balancer

Updates a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name, description, or status of a given shared load balancer.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0

Requête

URI Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
DataCenter chaîne Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Oui
LoadBalancerId chaîne ID of the load balancer to update Oui

Content Properties

Name Type Description Req.
nom chaîne Friendly name for new the load balancer Oui
description chaîne Description for new the load balancer Oui
status chaîne Status to create the load balancer with: enabled or disabled Non

Examples

JSON

{
	"name":"Updated Load Balancer",
	"description":"An updated load balancer"
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer.

Create Policy

Creates a new backup policy associated with the account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a brand new backup policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Requête

Content Properties

Name Type Description Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours -- this field is ignored if backupSchedule is defined Yes1
backupSchedule chaîne Quartz-flavored CRON expression describing the execution schedule for backups Yes1
clcAccountAlias chaîne The account alias that the Policy belongs to Non
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup Non
nom chaîne The name of the Policy Oui
osType chaîne 'Linux' or 'Windows' Oui
paths Array[string] A list of the directories that the Policy includes in each backup Oui
retentionDays integer The number of days backup data will be retained Oui

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "paths": [
    "/opt"
  ],
  "retentionDays": 7,
  "backupSchedule": "0 0 12 ? * TUE,SUN *"
}

Réponse

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
nom chaîne The name of the Policy
osType chaîne 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId chaîne The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/opt"
  ],
  "excludedDirectoryPaths": [],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * SUN *"
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Create Server Policies

Create multiple Server Policies under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

Note that the endpoint for this operation is the same as the standard Create Server Policy API, but an additonal header (Bulk-Operation: true) is required, and both the request and response bodies will be different than the single policy create.

When to Use It

Use this API operation when you want to create multiple Server Policies.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/193fccfc-c144-4052-98da-145eed825e0a/serverPolicies

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne The unique Id of an account policy Oui

Headers

Name Type Description Req.
Bulk-Operation boolean Must be set to "true" for the multi-server-policy API Oui

Content Properties

Name Type Description Req.
serverId chaîne Unique server name Oui
storageRegion chaîne Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC" Oui

Examples

JSON

[{
  "serverId": "UC1BAADTEST01",
  "storageRegion": "US WEST"
 },{
  "serverId": "IL1BAADTEST01",
  "storageRegion": "US WEST"
}]

Réponse

Response List Definition

Name Type Description
status chaîne Aggregate status for entire server policy creation request. 'SUCCESS', 'PARTIAL', 'FAILED'
success boolean Indicates if server policy creation was successful
error chaîne Provides details for server policy creation failure related to system or infrastructure
validationMessages chaîne Provides details for server policy creation failure related to parameter restrictions

Server Policy Definition

Name Type Description
serverPolicyId chaîne Unique Id of the Server Policy
accountPolicyId chaîne Unique Id of the Account Policy
serverId chaîne Unique server name
storageRegion chaîne Region where backups are stored
clcAccountAlias chaîne The account alias that the Policy belongs to
status chaîne The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
 "status": "PARTIAL",
 "createServerPolicyResponseList": [
  {
  "success": false,
  "error": "Failed to get server information for serverId=UC1BAADTEST01",
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": null,
    "accountPolicyId": null,
    "serverId": "UC1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": null,
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  },
  {
  "success": true,
  "error": null,
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": "80448207-332c-4f95-b82b-ac1fcb87b2c6",
    "accountPolicyId": "193fccfc-c144-4052-98da-145eed825e0a",
    "serverId": "IL1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": "PROVISIONING",
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  }
 ]
}

Create Server Policy

Create a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new Server Policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne The unique Id of an account policy Oui

Content Properties

Name Type Description Req.
clcAccountAlias chaîne The account alias that the Policy belongs to Oui
serverId chaîne Unique server name Oui
storageRegion chaîne Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC" Oui

Examples

JSON

{
  "clcAccountAlias": "BAAD",
  "serverId": "VA1BAADTEST01",
  "storageRegion": "USEAST",
}

Réponse

Entity Definition

Name Type Description
serverPolicyId chaîne Unique Id of the Server Policy
accountPolicyId chaîne Unique Id of the Account Policy
serverId chaîne Unique server name
storageRegion chaîne Region where backups are stored
clcAccountAlias chaîne The account alias that the Policy belongs to
status chaîne The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
"serverPolicyId": "085384ce-200e-4205-8a13-ae1d0bdc71cd"
"accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
"serverId": "VA1BAADTEST01"
"storageRegion": "US EAST"
"clcAccountAlias": "BAAD"
"status": "PROVISIONING"
"expirationDate": 0
"unsubscribedDate": 0
"storageAccountId": null
}

Delete Server Policy

Delete a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing Server Policy.

URL

Structure

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies/085384ce-200e-4205-8a13-ae1d0bdc71cd

Requête

URI Parameters

Name Type Description Req.
serverPolicyId chaîne Unique Id of the Server Policy Oui
accountPolicyId chaîne Unique Id of the Account Policy Oui

Réponse

The response will not contain JSON content, but will return the HTTP 204 No Content response upon successful deletion of the server policy. If an invalid account policy or server policy are passed in, a HTTP 404 Not Found response will be returned.

Get All Policies Eligible For ServerId

Returns a list of the backup policies that are eligible to be applied to the specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of policies that may be applied to a given server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/{serverId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/VA1ACMEDEMO01

Requête

URI Parameters

Name Type Description Req.
serverId chaîne Unique server name Oui

QueryString Parameters

Name Type Description Req.
limit integer Return up to this many results Non
offset chaîne Return results starting from this position in the list Non
sortBy chaîne Sort the results by the specified field Non
ascendingSort boolean Sort the sortBy field in ascending order Non

Réponse

Entity Definition

Name Type Description
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies eligible for the specified server
totalCount integer The total number of Policies eligible for the specified server

Account Policy Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
nom chaîne The name of the Policy
osType chaîne 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId chaîne The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 1",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 2",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/opt"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 7,
      "backupSchedule": "0 0 12 ? * SUN *",
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get All Regions

Retrieves a list of backup storage regions which are available in Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of backup storage regions which are available in Simple Backup Service.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/regions

Example

GET https://api.backup.ctl.io/clc-backup-api/api/regions

Réponse

Entity Definition

Name Type Description
messages Array[string] A list of messages associated with the Storage Region
nom chaîne The name of the Storage Region
regionLabel chaîne The label associated with the Storage Region

Examples

JSON

[
  {
    "name": "APAC",
    "regionLabel": "APAC (Singapore)",
    "messages": null
  },
  {
    "name": "GERMANY",
    "regionLabel": "EU (Germany)",
    "messages": null
  },
  {
    "name": "GREAT BRITAIN",
    "regionLabel": "EU (Ireland)",
    "messages": null
  },
  {
    "name": "US EAST",
    "regionLabel": "US East",
    "messages": null
  },
  {
    "name": "US WEST",
    "regionLabel": "US West",
    "messages": null
  },
  {
    "name": "CANADA",
    "regionLabel": "Canada",
    "messages": [
      "Backups stored in this region are NOT encrypted at rest"
    ]
  }
]

Get Datacenter List

Get a list of CLC Data Centers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of CLC Data Centers.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

Réponse

Entity Definition

Name Type Description
datacenters Array[string] Array of string values corresponding to each datacenter

Examples

JSON

{
  [13]
  0:  "CA1 - Canada (Vancouver)"
  1:  "CA2 - Canada (Toronto)"
  2:  "CA3 - Canada (Toronto)"
  3:  "DE1 - Germany (Frankfurt)"
  4:  "GB1 - Great Britain (Portsmouth)"
  5:  "GB3 - Great Britain (Slough)"
  6:  "IL1 - US Central (Chicago)"
  7:  "NY1 - US East (New York)"
  8:  "SG1 - APAC (Singapore)"
  9:  "UC1 - US West (Santa Clara)"
  10:  "UT1 - US Central (Salt Lake City)"
  11:  "VA1 - US East (Sterling)"
  12:  "WA1 - US West (Seattle)"
}

Get OS Types

Returns the list of valid OS types supported by Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of supported OS types.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

Example

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

Réponse

Entity Definition

Name Type Description
osTypes Array[string] Array of string values corresponding to each supported OS type

Examples

JSON

[
  "Linux",
  "Windows]
]

Get Policies

Gets a list of backup policies associated with an account. Calls to this operation must include a bearer token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of all policies associated with a given account.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies?limit=20&offset=0&withStatus=ACTIVE&sortBy=name&ascendingSort=true

Requête

QueryString Parameters

Name Type Description Req.
limit integer Return up to this many results Non
offset chaîne Return results starting from this position in the list Non
withStatus chaîne Filter results for either 'ACTIVE' or 'INACTIVE' Policies Non
sortBy chaîne Sort the results by the specified field Non
ascendingSort boolean Sort the sortBy field in ascending order Non

Réponse

Entity Definition

Name Type Description
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies associated with the Account
totalCount integer The total number of Policies associated with the Account

Account Policy Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
nom chaîne The name of the Policy
osType chaîne 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId chaîne The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Windows",
      "name": "Example Windows Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "C:\\backupthisup"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 1,
      "backupSchedule": "0 0 12 ? * SUN *",
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get Policy Details By Server

Get policy details by server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of policies and policy details for all policies associated with a specified server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails?serverId=VA1BAAPPRDTST01

Requête

QueryString Parameters

Name Type Description Req.
serverId chaîne Unique server name Oui
withStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED' Non

Réponse

Entity Definition

Name Type Description
accountPolicyId chaîne Unique ID of an account policy
osType chaîne 'Linux' or 'Windows'
nom chaîne The name of the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
accountPolicyStatus chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'
paths Array[string] A list of the directories that the Policy includes in each backup
backupProvider chaîne Not currently used
retentionDays integer The number of days backup data will be retained
backupIntervalHours integer The backup frequency of the Policy specified in hours-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
serverPolicyId chaîne Unique server policy identifier
serverId chaîne Unique server identifier
storageRegion chaîne Region where backups are stored. "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC"
serverPolicyStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED'
eligibleForBackup boolean Indicates if the account policy or server policy are active/inactive

Examples

JSON

{
  [2]
  0:  {
  "accountPolicyId": "5323900d-1288-47c8-9cce-e29790c9afbb"
  "osType": "Windows"
  "name": "TestingPolicy_1/12/16"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [2]
  0:  "C:\BackupFolder1"
  1:  "C:\BackupFolder12"
  -
  "backupProvider": null
  "retentionDays": 2
  "backupSchedule": "0 0 12 ? * SUN *"
  "serverPolicyId": "6d05d351-9cb8-4fed-bca6-064e3034caeb"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "CANADA"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }-
  1:  {
  "accountPolicyId": "16965823-5472-49c1-a38a-727dca9cb7a0"
  "osType": "Windows"
  "name": "C Drive"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [1]
  0:  "C:\"
  -
  "backupProvider": null
  "retentionDays": 21
  "backupIntervalHours": 2
  "serverPolicyId": "f37088d7-22ba-4704-ba61-25ecd2e8a086"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "US EAST"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }
}

Get Policy

Gets the backup policy associated with the specified accountPolicyId. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the details of a specific backup policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/4ca70660-f08a-407b-830d-e8e9c6c1d59a

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne The unique id associated with the backup policy to retrieve Oui

Réponse

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
nom chaîne The name of the Policy
osType chaîne 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId chaîne The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var"
  ],
  "excludedDirectoryPaths": [
    "/var/run"
  ],
  "retentionDays": 5,
  "backupSchedule": "0 0 12 ? * SUN *",
  "policyId": "4ca70660-f08a-407b-830d-e8e9c6c1d59a"
}

Get Restore Point Details

Gets a list of restore point details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to obtain restore point details for a specific serverPolicyId.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/restorePointDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/restorePointDetails?backupFinishedStartDate=2016-01-01&backupFinishedEndDate=2016-04-01

Requête

URI Parameters

Name Type Description Req.
serverPolicyId chaîne Unique Id of the Server Policy Oui
accountPolicyId chaîne Unique Id of the Account Policy Oui

QueryString Parameters

Name Type Description Req.
limit integer Limit the number of records returned Non
offset integer Non
inRetentionOnly boolean Non
backupFinishedStartDate chaîne Valid date format is 'YYYY-MM-DD' Oui
backupFinishedEndDate chaîne Valid date format is 'YYYY-MM-DD' Oui
sortBy chaîne Sort results by: [policyId, retentionDay, backupStartedDate, backupFinishedDate, retentionExpiredDate, backupStatus, filesTransferredToStorage, bytesTransferredToStorage, filesFailedTransferToStorage, bytesFailedToTransfer, unchangedFilesNotTransferred, unchangedBytesNotTransferred, filesRemovedFromDisk, bytesRemovedFromDisk] Non
ascendingSort boolean Non

Réponse

Entity Definition

Name Type Description
restorePointId chaîne Unique restore point identifier
policyId chaîne Unique policy identifier
retentionDays integer Days of retention applied to the restore point
backupFinishedDate chaîne Timestamp of backup completion
retentionExpiredDate chaîne Timestamp or retention expiration
restorePointCreationStatus chaîne 'SUCCESS', 'PARTIAL_SUCCESS', 'FAILED', or 'CANCELLED'
filesTransferredToStorage integer Number of backup files transferred to storage
bytesTransferredToStorage integer Total bytes of backup data sent to storage
filesFailedTransferToStorage integer Number of backup files that failed transfer to storage
bytesFailedToTransfer integer Total bytes of backup data that failed transfer to storage
unchangedFilesNotTransferred integer Number of unchanged files not requiring retransfer to storage
unchangedBytesInStorage integer Total bytes of unchanged data not requiring retransfer to storage
filesRemovedFromDisk integer Number of files removed from local disk
bytesInStorageForItemsRemoved integer Total bytes of data removed from local disk
numberOfProtectedFiles integer Number of files currently in storage for the restore point
backupStartedDate chaîne Timestamp of backup start

Examples

JSON

{
  "limit": 100
  "offset": 0
  "nextOffset": 0
  "results": [2]
    0:  {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401225505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T22:55:10.849Z"
        "retentionExpiredDate": "2016-04-07T22:55:05.277Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T22:55:05.277Z"
  }
  -1:   {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401214505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T21:45:10.802Z"
        "retentionExpiredDate": "2016-04-07T21:45:05.261Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T21:45:05.261Z"
  }
  "totalCount": 2
}

Get Server Policies

Gets a list of Server Policies associated to an Account Policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of all Server Policies attached to an Account Policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne Unique Id of the Account Policy Oui

QueryString Parameters

Name Type Description Req.
accountPolicyId chaîne Unique ID of an account policy Non
limit integer Return up to this many results Non
offset chaîne Return results starting from this position in the list Non
withStatus chaîne Filter results for either 'ACTIVE' or 'INACTIVE' Policies Non
sortBy chaîne Sort the results by the specified field Non
ascendingSort boolean Sort the sortBy field in ascending order Non

Réponse

Entity Definition

Name Type Description
limit integer The maximum number of results requested
offset integer The starting position in the list of results
nextOffset integer The next position in the list of results for a subsequent call
results Array[Server Policy] An array of the Server Policies associated with the Account Policy
totalCount integer The total number of Server Policies associated with the Account Policy

Server Policy Definition

Name Type Description
serverPolicyId chaîne The next position in the list of results for a subsequent call
accountPolicyId chaîne Unique Id of the Account Policy
serverId chaîne Unique server name
storageRegion chaîne Region where backups are stored
clcAccountAlias chaîne The account alias that the Policy belongs to
status chaîne The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId chaîne Not currently used

Examples

JSON

  {
  "limit": 1000
  "offset": 0
  "nextOffset": 0
  "results": [1]
      0:  {
          "serverPolicyId": "7796a750-db6a-4d6d-a9c0-93f729e9977e"
          "accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
          "serverId": "VA1BAADTEST01"
          "storageRegion": "US EAST"
          "clcAccountAlias": "BAAD"
          "status": "ACTIVE"
          "expirationDate": 0
          "unsubscribedDate": 0
          "storageAccountId": "f5c2c756-94b6-4b74-92e9-60f648caed15"
          }
  "totalCount": 1
  }

Get Server Policy

Get details of a specific server policy associated to an account policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get details for a specific server policy. Use the getServerPolicies API to obtain details for all server policies associated with an account policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne Unique ID of an account policy Oui
serverPolicyId chaîne Unique Id of the Server Policy Oui

Réponse

Entity Definition

Name Type Description
serverPolicyId chaîne Unique Id of the Server Policy
accountPolicyId chaîne Unique Id of the Account Policy
serverId chaîne Unique server name
storageRegion chaîne Region where backups are stored
clcAccountAlias chaîne The account alias that the Policy belongs to
status chaîne The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED', 'PENDING_INSTALL'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId chaîne Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Get Servers By Datacenter

Get a list of servers based on CLC Data Center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of servers associated with a CLC Data Center.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api//api/datacenters/{datacenter}/servers

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters/VA1%20-%20US%20East%20(Sterling)/servers

Requête

URI Parameters

Name Type Description Req.
centre informatique chaîne CLC Data Center Oui

Réponse

Entity Definition

Name Type Description
list Array[string] Array of string values corresponding to each server

Examples

JSON

{
  [3]
  0:  "VA1BAAPXAMPLE01"
  1:  "VA1BAAPXAMPLE02"
  2:  "VA1BAAPXAMPLE03"
}

Get Stored Data By Server Policy

Gets the amount of stored data for a server policy on a specified date. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to determine the amount of backed up data in storage for a server on a specific day.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/storedData

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/storedData?searchDate=2016-03-29

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne Unique account policy identifier Oui
serverPolicyId chaîne Unique server policy identifier Oui

QueryString Parameters

Name Type Description Req.
searchDate chaîne Valid date format is 'YYYY-MM-DD' Oui

Réponse

Entity Definition

Name Type Description
gigabytesStored chaîne Amount of stored backup data in gigabytes
bytesStored chaîne Amount of stored backup data in bytes

Examples

JSON

{
  "gigabytesStored": "0.541"
  "bytesStored": "581560320"
}

Patch Policy

Updates specific values of a server policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Because of the business rules that apply to this product, there are limited scenarios when this operation is allowed. Specifically, you may use this API operation when you want to change the status of a server policy from 'ERROR', 'PENDING_INSTALL', or 'PROVISIONING' to 'INACTIVE'. Other attempts to modify the server policy will result in errors.

URL

Structure

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne Unique ID of an account policy Oui
serverPolicyId chaîne Unique Id of the Server Policy Oui

Content Properties

Name Type Description Req.
op chaîne The patch operation to perform: 'add', 'remove', 'replace' Oui
path chaîne The only change allowed currently is to the status. Valid transitions are: ERROR to INACTIVE, PENDING_INSTALL to INACTIVE, and PROVISIONING to INACTIVE Oui
value chaîne The new value to set path to. Oui

Examples

JSON

{
  "op": "replace",
  "path": "/status",
  "value": "INACTIVE"
}

Réponse

Entity Definition

Name Type Description
serverPolicyId chaîne Unique Id of the Server Policy
accountPolicyId chaîne Unique Id of the Account Policy
serverId chaîne Unique server name
storageRegion chaîne Region where backups are stored
clcAccountAlias chaîne The account alias that the Policy belongs to
status chaîne The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId chaîne Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Update Policy

Updates a backup policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the settings of a backup policy. It can be used to modify the name, frequency, paths to include, and paths to exclude. Operating System and Retention may not be modified.

URL

Structure

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/107e6129-46b6-4b01-afcc-ea733db37214

Requête

URI Parameters

Name Type Description Req.
accountPolicyId chaîne The unique id associated with the backup policy to update Oui

Content Properties

Name Type Description Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours -- ignored if backupSchedule is defined Yes1
backupSchedule chaîne Quartz-flavored CRON expression describing the execution schedule for backups Yes1
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup Oui
nom chaîne The name of the Policy Oui
osType chaîne 'Linux' or 'Windows' Oui
paths Array[string] A list of the directories that the Policy includes in each backup Oui
policyId chaîne The unique Id associated with the Policy Oui
retentionDays integer The number of days backup data will be retained Oui
status chaîne 'ACTIVE' or 'INACTIVE' Oui

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Réponse

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule chaîne Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias chaîne The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
nom chaîne The name of the Policy
osType chaîne 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId chaîne The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status chaîne The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Add Webhook Target Uri

Add a target uri to the webhook for a specified event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a uri to the collection of targetUris in a webhook.

URL

Structure

POST https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris

Example

POST https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris

Requête

Uri Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
Event chaîne The name of the webhook event being configured Oui

Content Properties

Name Type Description Req.
targetUri chaîne A uri that will be called when the event occurs Oui

Examples

JSON

{ targetUri: "https://test.api/account/created" }

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Configurer des « webhooks » et des avis de consommation

Description

Webhooks make it possible to subscribe to key events that occur in the CenturyLink Cloud. In this article, we will walk through how to create a Webhook listener, configure a Webhook, and receive a notification. For general details on Webhooks, read the Webhook FAQ.

Prerequisites

  • Must have a CenturyLink Cloud account
  • Must be able to deploy applications to an internet-facing location that has legitimate SSL certificates

Detailed Steps

Build the Webhook Listener

Un auditeur webhook est simplement une application Web qui reçoit un message JSON par le biais de HTTP POST. A working example application written in Node.js can be downloaded from GitHub. When designing a Webhook listener, consider the following activities:

  1. Décidez à quels événements souscrire. Webhooks support Account, Alert, User, and Server events.

  2. Process HTTP POST requests. In the example Node.js application, this is done in the app.js file.

    app.post('/webhook/account', function(req, res){

    //extract the signature header
    var signatureHeader = req.get('Tier3-RsaSha1');

    //call function to send webhook data to client browser
    BroadcastAccountWebhook(req.body, signatureHeader);

    //send OK response to CenturyLink Cloud
    res.send("ok");

    })

  3. Handle the payload for each message type. In the example project, this is done in a client-side JavaScript file and the entire payload is shown to the user. A listener application that uses typed object definitions must be able to deserialize the JSON structures. Examples of each payload type can be found in the Webhooks FAQ.

Deploy the Webhook Listener

  1. Webhooks must be deployed to an internet-facing location that is reachable by the CenturyLink Cloud platform.

  2. Identify a host (public cloud IaaS, public cloud PaaS, or on-premises data center) with a valid (not self-signed) SSL certificate.

  3. Deploy the application and ensure that it's reachable. For this demonstration, the listener was deployed to a non-CenturyLink Cloud public Cloud Foundry environment hosted by Pivotal.
    Application exemple de webhooks

Configure a Webhook in the CenturyLink Cloud

  1. Go to the CenturyLink Control Portal, log in, and select the API option from the navigation menu.
    Control Portal Menu - API

  2. Switch to the Webhooks sub-tab and review the list of available Webhooks. You can configure unique endpoints for each individual Webhook. In the image below, notice that the Account.Updated Webhook was set with the URL to the listener web application. A Webhook will respond to events that occur in sub-accounts if the "include sub-accounts" checkbox is selected.
    Configuration des webhooks

  3. Click Save when the configuration is complete.

  4. Add Webhook URLs for any other Webhooks of interest.

Test the Webhook

  1. Déclenchez un événement dans la plateforme auquel le Webhook répondra. View the Webhook FAQ for a list of what platform events will trigger a Webhook notification. Pour faire déclencher le Webhook Compte.mis à jour précédent, modifiez un réglage comme l'adresse courriel.
    Mettre à jour l'info sur le compte

  2. Save the account change. Within seconds, the Webhook listener service should receive the notification message. Dans l'application échantillon, cette information est poussée au navigateur. Clicking on the updated account's name reveals both the full payload and the hashed signature value.
    Mettre à jour l'info sur le compte

Verifying the Webhook Signature

Each Webhook notification includes a signature attached in the Tier3-RsaSha1 header. This signature is generated by creating a SHA-1 hash from the JSON payload and encrypting it with an RSA private key. It can be verified by following these steps:

  • Generate a SHA-1 hash from the message body
  • Decrypt the signature using CenturyLink Cloud's public key (which can be found in the Webhook FAQ)
  • Compare these two values and confirm they are equal. If they're not, the message did not come from CenturyLink Cloud.

Though someone trying to be malicious may change the JSON message, they will not be able to get the correct signature to match up without the use of the private key. This confirms that the message indeed came from CenturyLink Cloud and not someone spoofing or tampering with the message in-flight.

Notice in the screenshot above that under the hashed signature value, there is a VERIFIED message in green. This is because the example application performs this verification and outputs the results. In the code above for the account Webhook handler, we retrieve the signature from the Tier3-RsaSha1 header. Later in the code, we verify the signature

function VerifySignature(data, signatureHeader) {
  var publicKey = fs.readFileSync(path.resolve(__dirname, 'public.pem')).toString();
  var key = new rsa(publicKey, 'pkcs8-public-pem', {"signingScheme":"sha1"});
  return key.verify(data, signatureHeader, 'utf8', 'base64');
}

If this verification failed because the message was tampered with or came from someone else, the following message would appear. Notice the message matches the one above, but signature does not.

Mettre à jour l'info sur le compte

Delete Webhook Target Uri

Delete a target uri from a webhook. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a single target uri from a particular webhook.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris?targetUri={uri}

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris?targetUri=https%3A%2F%2Ftest.api%2Faccount%2Fcreated

Requête

Uri Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
Event chaîne The name of the event from which the target uri will be deleted Oui
targetUri chaîne The uri that will be removed Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Delete Webhook

Delete a webhook for an event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete the webhook for an event. This will delete all the targetUris for the specified event.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

Requête

Uri Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
Event chaîne The name of the event for which the webhook will be deleted Oui

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Get Webhooks

Gets the details on the configured webhooks. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover all the webhooks that have been configured for every available event and get links to operations for modifying those webhooks.

URL

Structure

GET https://api.ctl.io/v2/webhooks/{accountAlias}

Example

GET https://api.ctl.io/v2/webhooks/ALIAS

Requête

Uri Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui

Réponse

Webhook Collection Entity Definition

Name Type Description
items Webhook[] A list of webhooks, one per available event

Webhook Entity Definition

Name Type Description
nom chaîne The name of the event that triggers the webhook
configuration Configuration Details about the webhook handling the event

Configuration Entity Definition

Name Type Description
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts
targetUris TargetUri[] The list of targets to be called when the event occurs

TargetUri Entity Definition

Name Type Description
targetUri chaîne A uri that will be called when the event occurs

Examples

JSON

{
  "items": [
    {
      "name": "Account.Created",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://uri.test/account/created"
          },
          {
            "targetUri": "https://api.test/account/created"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Deleted",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://api.test/account/deleted"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Alert.Notification",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Alert.Notification/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/v2/webhooks/RJP"
    }
  ]
}

Set Webhook

Change the configuration of a webhook for a specific event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the configuration of a webhook including the uris that get called when the event occurs and whether the uris are called when the event occurs in a sub-account.

URL

Structure

PUT https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

PUT https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

Requête

Uri Parameters

Name Type Description Req.
AccountAlias chaîne Short code for a particular account Oui
Event chaîne The name of the webhook event being configured Oui

Content Properties

Name Type Description Req.
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts Oui
targetUris TargetUri[] The targets called when the event occurs Non

TargetUri Entity Definition

Name Type Description Req.
targetUri chaîne A uri that will be called when the event occurs Oui

Examples

JSON

{
  recursive: true,
  targetUris: [
    { targetUri: "https://test.uri/account/created" },
    { targetUri: "https://test.api" }
  ]
}

Réponse

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Webhooks FAQ

Description

The CenturyLink Cloud supports Webhooks which send push notifications to an HTTP endpoint specified by the customer. This FAQ addresses commonly asked questions about the service. For a walkthrough of how to use Webhooks, see Configuring Webhooks and Consuming Notifications.

Q: What exactly is a Webhook?

A: Webhooks make it possible to create push notification solutions. Platform events (e.g. "server created") are sent in real-time to a web endpoint configured for the Webhook. Whenever an event occurs, a JSON message is sent as an HTTP POST request.

Q: Did CenturyLink Cloud invent the idea of Webhooks?

A: No, but we're among the first to use it in an IaaS cloud. Webhooks are in use today for a variety of web properties including Wordpress, Trello, and Zoho. CenturyLink Cloud sees value in embracing this model for public cloud customers who want to be more responsive to changes in their cloud account.

Q: In what scenario would I use a Webhook?

A: We've identified numerous use cases where Webhooks can replace or augment the components of existing processes:

  • Replace polling-based synchronization solutions. Customers often use request-response API operations to retrieve data about their assets in the CenturyLink Cloud. However, polling is fairly inefficient as the caller is simply asking "Do you have anything for me?" over and over again. With Webhooks, there's no longer a need to poll for changes. Instead, the CenturyLink Cloud immediately tells customers whenever key events occur in the platform.
  • Perform real-time data analytics. Customers can use this data to assess their cloud usage. For resellers, Webhooks provide an opportunity to observe server provisioning and detect trends. They could use it to watch for fraudulent signup scenarios my detecting abnormal combinations of account creation and server provisioning.
  • Monitor activities with security, compliance implications. For customers who closely govern their cloud usage, Webhooks provide the opportunity to immediately see what users are doing. Whether adding public IP addresses, or creating new user accounts, customers can quickly monitor and respond to activities that are counter to company policies.

Q: What triggers a Webhook?

A: There are currently Webhooks for four major categories: Accounts, Users, Alerts, and Servers.

  • Accounts. Triggered on account creation and deletion. Triggered on account changes including account status, business name, address, telephone, fax, and time zone.
  • Users. Triggered on user creation and deletion. Triggered on user changes including user status, password, security PIN, email address, alternative email address, first name, last name, title, office number, mobile number, fax number, time zone.
  • Alerts. Triggered when a user-defined alert policy threshold is exceeded, and when the server returns to a utilization level below the alert policy threshold.
  • Servers. Triggered on server creation and deletion. Triggered on server changes including server archive, server restore, convert to template, convert from template, add/delete/edit disks, edit CPU, edit memory, assigned Group, description, add/remove IP addresses, power on/off, and shutdown.

Q: What data is sent in the Webhook event notification?

A: Some push notification systems only send a bare minimum of information and ask the user to call-back for the full data payload. CenturyLink Cloud Webhooks send a full JSON-encoded payload AND include a URL to the referenced resource.

The Account event payload:

{
  "addressLine1": "112 112th Ave NE",
  "addressLine2": "Ste 300",
  "city": "Bellevue",
  "stateProvince": "WA",
  "country": "USA",
  "postalCode": "98004",
  "telephone": "800-buy-cloud",
  "status": "Active",
  "isManaged": true,
  "links": [
    {
      "rel": "self",
      "href": "/v2/accounts/DEMO"
    },
    {
      "rel": "parentAccount",
      "href": "/v2/accounts/T3N"
    }
  ],
  "accountAlias": "DEMO",
  "businessName": "Seroter Industries",
  "parentAlias": "T3N",
  "primaryDataCenter": "WA1"
}

The User event payload:

{
  "uri": "/v2/users/demo@user.com",
  "accountUri": "/v2/accounts/DEMO",
  "accountAlias": "DEMO",
  "userName": "demo@user.com",
  "emailAddress": "demo@user.com",
  "firstName": "Richard",
  "lastName": "Seroter",
  "status": "Active"
}

The Server event payload:

{
  "id": "WA1DEMOSERVER01",
  "name": "WA1DEMOSERVER01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.81.123.11"
      },
      {
        "public": "74.41.155.112",
        "internal": "10.81.123.14"
      }
    ],
    "alertPolicies": [
      {
        "id": "45866e6219e84ab786d07d4f570ba960",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/DEMO/45866e6219e84ab786d07d4f570ba960"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies/45866e6219e84ab786d07d4f570ba960",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 1,
    "diskCount": 1,
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 50,
    "disks": [
      {
        "id": "0:0",
        "sizeGB": 50,
        "partitionPaths": []
      }
    ],
    "partitions": [],
    "snapshots": [],
    "customFields": [
      {
        "id": 22,
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": 237,
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdBy": "demo@user.com",
    "createdDate": "2012-12-17T01:17:17Z",
    "modifiedBy": "demo@user.com",
    "modifiedDate": "2014-06-18T18:28:54Z"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01",
      "id": "WA1DEMOSERVER01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/DEMO/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/DEMO",
      "id": "demo"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/DEMO/serverPricing/WA1DEMOSERVER01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses/74.41.155.112",
      "id": "74.41.155.112",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

*Note that server delete events will only contain the accountAlias and name fields as the server has been deleted and any other information is no longer available.

The Alert event payload:

{
  "accountAlias": "DEMO",
  "serverName": "WA1DEMOSERVER01",
  "triggers": [
    {
      "data": {
        "cpu": 2,
        "cpuPercent": 39.34
      },
      "duration": "00:05:00",
      "metric": "cpu",
      "stateEndTime": "2014-06-18T18:23:46Z",
      "stateStartTime": "2014-06-18T18:20:00Z",
      "state": "notTriggered"
    }
  ]
}

Q: Where do I go to set a Webhook?

A: Webhooks are available at the Account-level under the API menu. There is now a sub-menu called "Webhooks." Customers can set a target URL for each Webhook event listed. Configuration des webhooks

Q: Can notifications be sent for events that occur within sub-accounts?

A: Yes. For each individual Webhook event, customers can specify whether they want sub-account events to ALSO be sent to the designated endpoint. If a parent account has the "include sub-accounts" checkbox selected, and a sub-account has specified their own Webhook endpoint for the same event, then a copy of the event notification is sent to both endpoints

Q: Are there any requirements for the service that receives the Webhook notification?

A: All Webhook listener services must support secure HTTP transport via HTTPS. The data transmitted in the event may be sensitive and shouldn't travel over unprotected channels. Secondly, listener services must be on the public internet in a location reachable by the CenturyLink CLoud platform. If a customer plans on consuming this data within an internal system, consider using a reverse proxy or another mechanism to forward traffic from a public-facing web service to an internal system.

Q: How can listener services be sure that it was CenturyLink Cloud that sent the message and not someone spoofing you?

A: While SSL ensures that the message cannot be read in transit, it doesn't protect you from rogue callers who target your public endpoint. Each Webhook notification includes a signature hash of the message payload. The Tier3-RsaSha1 header is signed with our private key, leveraging the JSON payload as input. This signature can be verified with the following public key and the received JSON body. Customers can use this process to ensure that the message wasn't tampered with. For more details and sample code on how to verify the signature, see Configuring Webhooks and Consuming Notifications.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnmwsVLJ22Y8lmnk+1fI/
JKkm4bM1GvggI7DN10KIoPDgBbNcePZqcFayDdmVuq/jL9MFBrqFSfVszgdq8OWF
G9lEB5vP29K/N+0kRg5V2NDXddI5AOzx6jDjkNM/jjb45UXeDcPzMMdMOl/ds6uT
p6mbfG3U8dWqM/if7mzjEbbhYkBM3OuacEFk38Tkm49IJ4jHnC0p9qWO2iaxJqRc
08M2cJ+yKcFudCVKX8ANE6g6YKK+5aSabxfHX83Vjr4I0kpqo0cfP4aSW/CPDUZ7
yR4bFiy5Wv2de2V+FOGVBQF+/viSzrtrwQjUOJViuxEnifc06xuDF0QFta9anz4d
LQIDAQAB
-----END PUBLIC KEY-----

Q: How soon after an event occurs does a Webhook notification get sent?

A: As soon as the event occurs in the CenturyLink Cloud platform, it is routed through our messaging infrastructure and sent to each Webhook endpoint. In reality, this means that messages are often received within 5 seconds of the event occurring.

Q: What happens if the destination is unreachable?

A: There is no guaranteed delivery with CenturyLink Cloud Webhooks. We make a single attempt to send a message to the designated endpoint and if it fails, it is not retried. This means two things: (1) design your endpoints to be highly available and withstand failures of any single component in the solution, and (2) rely on a combination of Webhooks and daily web service API calls to ensure that your local repositories stay in sync.

Q: Are there more Webhooks on the way?

A: Yes! We have ideas for additional Webhooks to add to the platform, but would like to hear from you. If you have suggestions for other Webhooks, send an email to features@ctl.io.