REST API examples

This topic provides examples of tasks that you can perform in Deploy using the REST API. These examples include how to: create a directory and several infrastructure CIs in the directory, add and remove a CI from an environment, and delete a CI.

Using the Deploy REST API, you can execute different commands to create, edit, or delete configuration items (CIs) in Deploy. You can access the Deploy REST API via a URL of the form: http://[host]:[port]/[context-root]/deployit/[service-resource].

In the following examples:

• The credentials being used are user name amy and password secret01.
• Deploy is running at http://localhost:4516.
• The cURL tool is used to show the REST calls.
• The specified XML files are stored in the location from which cURL is being run.

Create a directory

This REST call uses the RepositoryService to create a directory, this is a core.Directory CI type.

Input

If the CI data is stored in an XML file:

curl -u amy:secret01 -X POST -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory -d@directory.xml

If the CI data is stored in a JSON file:

curl -u amy:secret01 -X POST -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory -d@directory.json

Content of the XML file

<core.Directory id="Infrastructure/SampleDirectory">
</core.Directory>

Content of the JSON file

{
  "type": "core.Directory",
  "id": "Infrastructure/SampleDirectory"
}

Response

<core.Directory id="Infrastructure/SampleDirectory" token="f3bc20b4-3c67-4e59-aa7b-14f3d8c62ac5" created-by="amy" created-at="2017-03-13T21:00:40.535+0100" last-modified-by="amy" last-modified-at="2017-03-13T21:00:40.535+0100"/>

Create an SSH host

This REST call uses the RepositoryService to create an SSH host, this is a overthere.SshHost CI type. The properties that are available for the CI are described in the Remoting Plugin Reference.

Input

If the CI data is stored in an XML file:

curl -u amy:secret01 -X POST -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost -d@ssh-host.xml

If the CI data is stored in a JSON file:

curl -u amy:secret01 -X POST -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost -d@ssh-host.json

Content of the XML file

<overthere.SshHost id="Infrastructure/SampleDirectory/SampleSSHHost">
  <address>1.1.1.1</address>
  <connectionType>INTERACTIVE_SUDO</connectionType>
  <os>UNIX</os>
  <port>22</port>
  <username>sampleuser</username>
  <password>secret02</password>
  <sudoUsername>root</sudoUsername>
</overthere.SshHost>

Content of the JSON file

{
  "type": "overthere.SshHost",
  "address": "1.1.1.1",
  "connectionType": "INTERACTIVE_SUDO",
  "os": "UNIX",
  "port": "22",
  "username": "sampleuser",
  "password": "secret02",
  "sudoUsername": "root",
  "id": "Infrastructure/SampleDirectory/SampleSSHHost"
}

Response

<overthere.SshHost id="Infrastructure/SampleDirectory/SampleSSHHost" token="f2936b5c-b553-46be-b40a-f7528c27aa65" created-by="amy" created-at="2017-03-13T21:12:38.256+0100" last-modified-by="amy" last-modified-at="2017-03-13T21:12:38.256+0100">
  <tags/>
  <os>UNIX</os>
  <puppetPath>/usr/local/bin</puppetPath>
  <connectionType>INTERACTIVE_SUDO</connectionType>
  <address>1.1.1.1</address>
  <port>22</port>
  <username>sampleuser</username>
  <password>{b64}lINyyCcWc8NK7TTTESBLoA==</password>
  <sudoUsername>root</sudoUsername>
</overthere.SshHost>

Create a Tomcat server

This REST call uses the RepositoryService to create an Apache Tomcat server, this is a tomcat.Server CI type. The properties that are available for the CI are described in the Tomcat Plugin Reference.

Input

If the CI data is stored in an XML file:

curl -u amy:secret01 -X POST -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer -d@tomcat-server.xml

If the CI data is stored in an JSON file:

curl -u amy:secret01 -X POST -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer -d@tomcat-server.json

Content of the XML file

<tomcat.Server id="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer">
  <home>/opt/apache-tomcat-8.0.9/</home>
  <startCommand>/opt/apache-tomcat-8.0.9/bin/startup.sh</startCommand>
  <stopCommand>/opt/apache-tomcat-8.0.9/bin/shutdown.sh</stopCommand>
  <startWaitTime>10</startWaitTime>
  <stopWaitTime>10</stopWaitTime>
</tomcat.Server>

Content of the JSON file

{
  "type": "tomcat.Server",
  "home": "/opt/apache-tomcat-8.0.9/",
  "startCommand": "/opt/apache-tomcat-8.0.9/bin/startup.sh",
  "stopCommand": "/opt/apache-tomcat-8.0.9/bin/shutdown.sh",
  "startWaitTime": "10",
  "stopWaitTime": "10",
  "id": "Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer"
}

Response

<tomcat.Server id="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer" token="b3378d43-3620-4f69-a2e1-d0a2ba6178de" created-by="amy" created-at="2017-03-13T21:33:16.558+0100" last-modified-by="amy" last-modified-at="2017-03-13T21:33:16.558+0100">
  <tags/>
  <envVars/>
  <host ref="Infrastructure/SampleDirectory/SampleSSHHost"/>
  <home>/opt/apache-tomcat-8.0.9/</home>
  <startCommand>/opt/apache-tomcat-8.0.9/bin/startup.sh</startCommand>
  <stopCommand>/opt/apache-tomcat-8.0.9/bin/shutdown.sh</stopCommand>
  <startWaitTime>10</startWaitTime>
  <stopWaitTime>10</stopWaitTime>
</tomcat.Server>

Create a Tomcat virtual host

This REST call uses the RepositoryService to create a Apache Tomcat virtual host, this is a tomcat.VirtualHost CI type. The properties that are available for the CI are described in the Tomcat Plugin Reference.

Input

If the CI data is stored in an XML file:

curl -u amy:secret01 -X POST -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost -d@tomcat-virtual-host.xml

If the CI data is stored in a JSON file:

curl -u amy:secret01 -X POST -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost -d@tomcat-virtual-host.json

Content of the XML file

<tomcat.VirtualHost id="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost">
</tomcat.VirtualHost>

Content of the JSON file

{
  "type": "tomcat.VirtualHost",
  "id": "Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost"
}

Response

<tomcat.VirtualHost id="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost" token="24143636-fec4-4f1f-a055-c10f8f0bd439" created-by="amy" created-at="2017-03-13T21:37:11.540+0100" last-modified-by="amy" last-modified-at="2017-03-13T21:37:11.540+0100">
  <tags/>
  <envVars/>
  <server ref="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer"/>
  <appBase>webapps</appBase>
  <hostName>localhost</hostName>
</tomcat.VirtualHost>

Add the virtual host to an environment

This REST call uses the RepositoryService to add the Apache Tomcat virtual host created above to an environment, this is a udm.Environment CI type. The properties that are available for the CI are described in the UDM CI Reference.

Input if the environment does not exist in Deploy

If the CI data is stored in an XML file:

curl -u amy:secret01 -X POST -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.xml

If the CI data is stored in a JSON file:

curl -u amy:secret01 -X POST -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.json

Input if the environment exists and is called TestEnv

If the CI data is stored in an XML file:

curl -u amy:secret01 -X PUT -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.xml

If the CI data is stored in a JSON file, the environment exists in Deploy, and it is named TestEnv:

curl -u amy:secret01 -X PUT -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.json

Content of the XML file

<udm.Environment id="Environments/TestEnv">
  <members>
     <ci ref="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost" />
  </members>
</udm.Environment>

Content of the JSON file

{
  "type": "udm.Environment",
  "members": [
    {"ci-ref": "Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost"}
  ],
  "id": "Environments/TestEnv"
}

Response

<udm.Environment id="Environments/TestEnv" token="95b28b83-0c2c-4229-84a5-e62bd1108bab" created-by="amy" created-at="2017-03-14T08:41:30.175+0100" last-modified-by="amy" last-modified-at="2017-03-14T08:59:14.962+0100">
  <members>
    <ci ref="Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost"/>
  </members>
  <dictionaries/>
  <triggers/>
</udm.Environment>

Remove the virtual host from the environment

Important: You must completed this section before you can delete the virtual host CI from Deploy.

This REST call uses the RepositoryService to remove the Apache Tomcat virtual host created above from the TestEnv environment.

Input

If the CI data is stored in an XML file:

curl -u amy:secret01 -X PUT -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.xml

If the CI data is stored in an JSON file:

curl -u amy:secret01 -X PUT -H "Content-type:application/json" http://localhost:4516/deployit/repository/ci/Environments/TestEnv -d@environment.json

Content of the XML file

<udm.Environment id="Environments/TestEnv">
</udm.Environment>

Content of the JSON file

{
    "type": "udm.Environment",
    "id": "Environments/TestEnv"
}

Response

<udm.Environment id="Environments/TestEnv" token="597ac2cb-2f0d-484b-848b-ab027ab8e70f" created-by="amy" created-at="2017-03-14T08:41:30.175+0100" last-modified-by="amy" last-modified-at="2017-03-14T10:18:04.629+0100">
  <members/>
  <dictionaries/>
  <triggers/>
</udm.Environment>

Delete the Tomcat virtual host

Important: You must Remove the virtual host from the environment before you can delete the virtual host CI from Deploy.

This REST call uses the RepositoryService to delete the Apache Tomcat virtual host created above from Deploy.

Input

curl -u amy:secret01 -X DELETE -H "Content-type:application/xml" http://localhost:4516/deployit/repository/ci/Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost

Response

If the virtual host was successfully deleted, you will not see a response message.

If you did not remove the virtual host from the environment, you will see:

Repository entity Infrastructure/SampleDirectory/SampleSSHHost/SampleTomcatServer/SampleVirtualHost is still referenced by Environments/TestEnv