How to create, read, update, and delete configuration items using the XL Deploy REST API

Follow

Michael Deypalan -

Common maintenance activities when running XL Deploy are adding, modifying, and removing items from its repository. This is especially the case for infrastructure and environment configuration items (CIs) that are not published to XL Deploy automatically in the way deployment packages usually are.

Of course, you want to automate these kind of activities as much as possible, too. Many of our users (primarily those not using XL Scale ;-)) have linked XL Deploy to their cloud management and provisioning tools so that, for example, a new virtual machine automatically "registers itself" with XL Deploy by means of a post-create hook.

Here, we'll use curl to go through an example of the XL Deploy REST API calls you'll need to make such a scenario work, specifically:

  • Creating a new CI
  • Reading an existing CI from the repository
  • Updating the properties of an existing CI
  • Deleting a CI from the repository

Creating a new CI

Use  POST /repository/ci/{ID:.*?} to create a new CI. Here, we'll create a new overthere.LocalHost CI with ID Infrastructure/my-new-ci.

INPUT:

curl -u<username>:<password> -X POST -H "Content-type:application/xml" http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci -d@/tmp/read-ci.xml

Content of /tmp/read-ci.xml:

<overthere.LocalHost id="Infrastructure/my-new-ci">

  <os>UNIX</os>

</overthere.LocalHost>

OUTPUT:

<overthere.LocalHost id="Infrastructure/my-new-ci" token="61cfc7c5-9ea5-4883-9a98-ae721f678aaa">

  <os>UNIX</os>

</overthere.LocalHost>

The description of the CI, as it was actually saved, is returned. This may differ from the input XML; that is, it may contain properties with default values that were not specified in the input.

If you want to create a CI that is linked to an artifact (although this is usually the case only for CIs in deployment packages), take a look at the version of the API call that takes a multipart ArtifactAndData parameter. An example would be:

**

INPUT:**

curl  -u<username>:<password>-X POST -H "Content-type:multipart/form-data" http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Applications/forDatabase/1.0/MySQL -F configurationItem=@/tmp/create_ci_with-data.xml -F filename=sqlScripts.zip -F fileData=@/tmp/sqlScripts.zip

Content of create_ci_with-data.xml:

<sql.SqlScripts id="Applications/forDatabase/1.0/MySQL" file="MySQL/sqlScripts.zip">

<tags />

<scanPlaceholders>true</scanPlaceholders>

</sql.SqlScripts>

OUTPUT:

<sql.SqlScripts id="Applications/forDatabase/1.0/MySQL" token="67dcd04b-6a71-40ef-a3ec-de2543bcfc3c">

<tags/>

<scanPlaceholders>true</scanPlaceholders>

<placeholders/>

<checksum>c04b05d7f98f5b7c919233b3c819f28a7a05f585</checksum>

</sql.SqlScripts>

 

The general structure for the XML representing the configuration item is described here; you can find the specific properties that the CI supports in the documentation of the appropriate plugin (for example,  in the Remoting Plugin Manual for overthere.LocalHost). An easy way to get a sample of the XML for a certain type is to use the  UI or  CLI to create a dummy CI of that type and then use the REST API to read it.

Which brings us to...

Reading an existing CI from the repository

Use  GET /repository/ci/{ID:.*?} to read an existing CI from the repository.

INPUT:

curl -u<username>:<password> http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci

OUTPUT:

<overthere.LocalHost id="Infrastructure/my-new-ci" token="eb5cacc9-8beb-447f-8e12-4756151f8308">

  <os>UNIX</os>

</overthere.LocalHost>

We need to store the output of this call in a temporary location because we want to update this CI in the next call.

The "token" included in the return is a generated value that is used to prevent concurrent modifications to the repository. If you try to update an existing CI, the server will compare the value of the token you pass in to the current value on the CI. If they are different, it means that the CI has been updated since you read the value, and the server will return a 409 error.

Updating the properties of an existing CI

Let's assume we saved the output of the previous call in /tmp/read-ci.xml. We can then modify any attributes we want to change in the file and use  PUT /repository/ci/{ID:.*?} to update the CI in the repository.

INPUT:

curl -u<username>:<password> -X PUT -H "content-type:application/xml" http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci -d@/tmp/read-ci.xml

Content of /tmp/read-ci.xml:

<overthere.LocalHost id="Infrastructure/my-new-ci" token="eb5cacc9-8beb-447f-8e12-4756151f8308">

  <os>WINDOWS</os>

</overthere.LocalHost>

 

OUTPUT:

<overthere.LocalHost id="Infrastructure/vm1" token="bab17047-9614-48b6-a741-1081a8541b48">

  <os>WINDOWS</os>

</overthere.LocalHost>

Again, take a look at the version of the command that takes a multipart ArtifactAndData parameter if you're looking to update the artifact associated with the CI.

Deleting a CI from the repository

Finally, we can use  DELETE /repository/ci/{ID:.*?} to delete our CI from the repository.

curl -u<username>:<password> -X DELETE http://<xl-deploy-server>:<xl-deploy-port>/deployit/repository/ci/Infrastructure/my-new-ci

Have more questions? Submit a request