How to: Create, Read, Update, and Delete Configuration Items using the Deploy REST API

Overview

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.

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 /tmp/read-ci.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>

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.

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 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

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

Additional information

For more information on using the REST API with XL Deploy, please browse to the REST API reference on the Developer Docs portal and select your version