DevOps info

UrbanCode Deploy REST API – The udclient is your friend

Sometimes the formal documentation for IBM UrbanCode Deploy isn’t the best way to explore the API. 

 

 

 

You can discover the REST API services provided by your UCD server by using this URL:
https://yourserver:port/cli/application.wadl?detail=true 

The ?detail=true is optional and gives you extra detail.

This is the Web Application Description Language (WADL) of the servers REST API.  It’s a very long XML document that isn’t very human friendly.


Fortunately, the udclient comes to your rescue as it also reads the WADL but presents the information in a friendlier form.  For example,

udclient  --weburl https://yourserver:port --username admin --password admin --help

Will provide a list of all the available UCD REST endpoints in the version of the server you run it against.

If you want to find the parameters of a REST API interface you can do things like:

udclient --weburl https://yourserver:port --username admin --password admin setApplicationProperty --help

The udclient will give you more information about that specific API and what’s expected.


Some API’s, like the one above, require you to provide a JSON input.  Using the -t option instead of –help to the command will output a sample template for you to use as a basis for using the API e.g.

udclient --weburl https://yourserver:port --username xxx --password xxxx setApplicationProperty -t

{
“application”: “Name or ID of the application”,
“name”: “Property name”,
“value”: “Property value (optional)”,
“isSecure”: “Whether the property is secure; the default is the current state of the property, or
false if the property is not yet specified (optional)”
}


Sometimes the example templates and outputs in the documentation aren’t accurate so its worth using the udclient to see what is actually required/returned.

For example, using the API endpoint getSystemConfiguration actually returns 66 properties in UCD v7.1 but the documentation example only lists 24.  So if you rely on the documentation you might conclude that what you want isn’t available when in fact it could be.

Because udclient works off of the WADL of your server it knows about all of the REST API’s, not just the ones in the documentation.  If you examine the API method list for a UCD 7.1 server, you will find these API’s that aren’t documented but which udclient knows about:

  • createDeploymentTrigger
  • createZOSVersion
  • deleteDeploymentTrigger
  • deleteFrontendServer
  • getDeploymentTrigger
  • getDeploymentTriggers
  • getFrontendServers
  • getUsersThatCanRunDeploymentTriggers

The udclient is your friend and you should use it to discover what the UCD server version you have is actually capable of.

Alan Murphy photo

Alan Murphy

IBM Cloud, DevOps, IT Specialist, Cloud Integration Expert Labs

Alan Murphy is a services consultant who has worked with clients to help them adopt new tools and processes for the last 20 years. UrbanCode Deploy and DevOps have been his focus for the last 5 years. He also develops tools to assist clients in tool adoption and blogs on an occasional basis.