The DeployHub Application Programming Interface (API) is a web-based RESTful-style API that allows DeployHub to be integrated with other tools. The API allows DeployHub objects to be queried, modified, or created, and for deployments to be instigated. Knowledge of RESTful API call conventions and JSON encoding standards is assumed.


Calls made to the API return JSON formatted results. All calls return a “success” Boolean attribute which is either true (the call was successful) or false (the call failed in some way). If “success” is false, then the string attribute “error” is set which returns the reason for the failure.


Example:


{

               "success": false,

               "error": "Not logged in"

}


The “success” flag is always at the top level of the JSON result structure. For example, here is a result returned from the DeployHub API when a query is made for an Application:


Query Issued:


http://re-host:8080/dmadminweb/API/Application/demoapp?latest=Y


Result:


       {

               "success": true,

               "result": {

                       "approvals": [

                       ],

                       "branch": "Branch 1a",

                       "Domain": "GLOBAL.Test",

                       "id": 187,

                       "name": "demoapp;8",

                       "ownerUser": "admin",

                       "predecessor": {

                               "id": 174,

                               "name": "demoapp;5",

                               "summary": ""

                       },

                       "rejections": [

                       ],

                       "summary": ""

               }

}

You can see that “success” is true and there is a “result” JSON object containing details of the queried Application.


Establishing a Connection to DeployHub

When issuing calls to the API, the client Application must either first issue a “login” call, specifying the Username and password or must specify the Username and password in each individual call to the API.


Login with Separate API Call


Query Issued:


http://re-host:8080/dmadminweb/API/login?User=admin&pass=admin



Result:


{

       "success": true,

}


The result will include a JSESSIONID cookie. Include this in subsequent calls to the API.



NOTE: The client Application must store this JSESSIONID cookie and ensure that it is reused whenever a subsequent call to the API is made. The exact method by which this can be achieved will depend on the client. An example of how this is done with cURL is shown in the Appendix.

NOTE: When calling the DeployHub API from inside DMScript (the DeployHub built-in scripting language), the JSESSIONID value for the logged-in User is available via a global variable ($JSESSIONID). This can be used to allow DMScript to call the DeployHub API without the need for an explicit second login. See the DMScript  Section for more information on using DMScript.


Specifying the Username and password in the query:


Query Issued:


http://re-host:8080/dmadminweb/API/Application/demoapp?latest=Y&User=admin&pass=admin


Result:


{

       "success": true,

       "result": {

               "approvals": [

               ],

               "branch": "Branch 1a",

               "Domain": "GLOBAL.Test",

               "id": 187,

               "name": "demoapp;8",

               "ownerUser": "admin",

               "predecessor": {

                       "id": 174,

                       "name": "demoapp;5",

                       "summary": ""

               },

               "rejections": [

               ],

                               "requests": [

                               ]

                       }

}

Object Accessibility

The objects that are accessible via the API are restricted based on the logged-in User. Only objects that are contained within the User’s home Domain and any Sub-Domains are accessible via the API (just as they would be through the graphical web interface).


If a requested object does not have “read” permission then it cannot be accessed via the API. Similarly, attempting to modify objects which do not have the appropriate “change” permission is also prohibited. In such cases, the “success” flag returned is “false” and the error is “Permission Denied”.



Identifying Objects

When making calls to the DeployHub API it is often necessary to identify an object on which you want to operate. For example, if you wish to query an Environment you would specify the name of the Environment in the query.


Example:


Query Issued:


http://re-host:8080/dmadminweb/API/Environment/demoenv  


Result:


{

       "success": true,

       "result": {

               "Applications": [

                       {

                               "completed": "",

                               "deploymentid": 1019,

                               "exitcode": -1,

                               "id": 118,

                               "name": "AS400App",

                               "predecessorid": 0,

                               "Versionid": 118,

                               "Versionname": "AS400App"

                       }

               ],

               "Domain": "GLOBAL.Test",

               "id": 1,

               "name": "demoenv",

               "ownerUser": "admin",

               "summary": "Demo Environment"

       }

}


However, this only works if the name of the Environment is unique in your Domain hierarchy.


Consider this scenario:


Sub-Domains with Environments


In the DeployHub model, an object name only has to be unique within a particular Domain. Here, the “Openmake” Domain has two Sub-Domains, “UK” and “USA”. Each regional Domain has its own “demoenv” Environment.


Assume the UK and the USA teams have their own logins with home Domains of “UK” and “USA” respectively. If you login to the API using an ID who is a member of the UK team then there is no issue – your home Domain is “UK” and you only have access to “your” demoenv and therefore you get the result for that Environment. Similarly, a User in the USA who logs into the API with their ID has “USA” as their home Domain and they only have access to their “demoenv” Environment.


But supposing you use an ID whose home Domain is the “Openmake” Domain? How does DeployHub know which “demoenv” Environment you want?


In these circumstances, you’ll get an error returned:


Query Issued:


http://re-host:8080/dmadminweb/API/Environment/demoenv  


Result:

{

       "success": false,

       "error": "Environment demoenv is Ambiguous",

}


There are two ways of fixing this issue:


  • Qualify the name of the object
  • Use the internal object ID.



Using cURL to access the API        


Here is an example of how to use cURL to access the DeployHub API.


First, we need to login. This operation will return a session ID. We use cURL’s –cookie-jar option to store this session ID in the file C:\temp\session.txt


curl --data "User=omadmin&pass=ompassword" --cookie-jar c:\temp\session.txt http://mac:8080/dmadminweb/API/login


If the Username/password combination is correct, the User is logged in and the success indication is returned.


{"success":true}


The JSESSIONID is stored in the cookie which is stored in the file:

C:\temp\session.txt


Now, we can call any of the other API interfaces by specifying the same file in which we stored the session ID returned from the login call. For example, this will return a JSON array containing all the servers in our home and Sub-Domains to which we have view access:


curl --data "all=Y" --cookie c:\temp\session.txt http://mac:8080/dmadminweb/API/servers