Using the API to Create and Configure a Server

Updated by Bryan Friedman on Apr 15, 2015

Description

The CenturyLink Cloud API can be used to perform the same actions programmatically as you can from within the Control Portal. Oftentimes multiple API calls are required to perform a particular task, and this may include waiting for asynchronous jobs to complete. Particularly in these cases, it's important to make sure to use a very prescriptive sequence for the calls to ensure success. The below example shows one such sequence for authenticating, creating a server, updating the server information, and restarting it.

For more details about the specific API functions used below, you may reference the complete API documentation.

Steps

We will use ALIAS as the account alias for all the calls below and will build our server in the WA1 data center. As shown below, all HTTP requests must include the Content-Type header set to application/json.

2. Get Deployment Capabilities

We first need to gather some details that will be required to create a new server. Most of this information is available via the deployment capabilities API call which can be retrieved using the following request:

The response should be similar to the following (but may also include additional information). We are particularly interested right now in the networkId listed in the deployableNetworks section as well as the name attribute of each item in the list of templates. These represent the network we wish to deploy our server to and the template we wish to be used on the server. We will use these values in a subsequent to create the server.

3. Get Available Groups

Next we need to decide which group to create our server in and retrieve the UUID to pass to the create server method. To get a list of available groups, we first retrieve the root group for the given account and data center using the following request (note the groupLinks=true query parameter that is required in this case):

We get back a number of links to other resources related to this data center (not all shown below). Notice the deploymentCapabilities endpoint that we've already used as well as the link to create a server. Most importantly, though, we see the link and identifier for the root data center group for this account.

4. Create a Server

To create a server we use the following request. Notice in the JSON payload we are using the groupId from our previous call to the groups endpoint as well as the sourceServerId (the desired template name) and networkId we chose from the deployment capabilities call above. We also include all of the other required parameters as outlined in the Create Server API Documentation.

We get back the following response. Notice the HTTP status is a 202 ACCEPTED. Also in this message we get two important links that we will use to call in our subsequent steps. The first one is the status of the asyncronous job that runs to build the server. The second self link is used to query the server itself. (The server name will generated based on the provided name and other parameters like account alias and data center code. Because the name is generated during the server build process and it is not yet built, this URL uses the UUID rather than the name of the server and thus requires the uuid=True query parameter.)

Before the server build job starts the status will be notStarted and while it is still running, the status will be executing. Once it is completed it should show succeeded.

200 OK
{ "status":"executing" }

In most cases, the status should continue to be polled until the succeeded status is reached before performing any additional action on the server.

Get Server

Regardless of the build status, we can query the server directly using the server link returned in the create server response above. Make sure to include the uuid=True query parameter to let the API know we are referencing the server using the UUID instead of the alias.

The response provides the details of the server in its current state. Notice the status field is set to underConstruction, meaning the server is not ready for use yet. (For managed servers, even after the job status has been set to succeeded, the server status will remain underConstruction until the server has been completely set up with the necessary services when it will be set to active.)

A few minutes later (after the job status is succeeded) we call the same method and see the server status is now active and there is additional information about the server including the name, IP address, and disk information.

Update Server Description

First, we will update the server description using the following request. (We are using the server name in the URI now since it is known from the previous call, but we could continue to use the UUID if we wanted to however we would have to add the uuid=True query parameter as we did above.)

Thank you for your submission. A representative will be reaching out to you within 24 hours.

First Name

Last Name

Email

Phone Number

Company (optional)

Job Title (optional)

Comments (optional)

What type of support do you need?

We have expert agents ready to assist you,
whether you're using Cloud Application Manager or any one of
the services available on the CenturyLink Cloud platform.
Click below to be directed to the appropriate team.