The uDeploy REST API

If you use IBM Urbancode Deploy (as uDeploy is now called) at all, you will notice its simplicity.  And rightly so as a deployment automation tool should not re-invent the way deployment automation is done.  Urbancode Deploy simply organizes and collects deployment processes and steps.  Once a deployment is successful, any good deployment automation solution should be able to repeat that deployment over and over again with no trouble.

On the other hand, the integrations with other tools, both as a consumer and a producer, provide the real value.  And a valuable part of Urbancode Deploy’s integration capabilities is its REST API.  There are 3 ways to get information about the API.

1) The documentation – this is unfortunately not your best bet.  It is out of date and lacks a lot of necessary detail.

2) The Application WADL file – it does exists in the uDeploy server folder structure.  But it is hard to decipher and also leaves out the json details.

3)  Browser development tools – This is the method that has been the most successful for me.  I use Chrome and its developer tools allow you to see the network traffic occuring as  you navigate the uDeploy web pages.  The uDeploy user interface heavily utilizes the REST API.  But capturing the network traffic as you navigate, you can see the specific rest calls that are occuring and examine the json payload both in and out.


I sought to build something that exercises the uDeploy REST API.  What I came up with is an example of how you can solve a common uDeploy requirement.  The process of onboarding an application to uDeploy involves many mouse clicks and an understanding of how to navigate the user interface.  As I said above, the concepts are easy once you understand them, but to onboard thousands of applications does not scale if you use the user interface.  Plus you must train people on how to get their applications into uDeploy.

So I built a small website that captures some basic information about an application, its components, and its environments, and does the bulk of the setup work in uDeploy via the REST APIs.   I wanted to be able to capture the information in a way that a development team would understand yet not need to know anything about uDeploy and its structure.

You can see a demo of this sample application at this link:

10-3-2013 2-53-54 PM

I would welcome any feedback.



12 thoughts on “The uDeploy REST API

  1. Quick couple of questions if you have the time.
    I am attempting to use the REST API, but having multiple issues.
    My main issue is I am getting 2 errors.
    First I am getting: The server committed a protocol violation. Section=ResponseStatusLine
    and second I am getting a not authorized error.
    To attempt to resolve the second, I changed my code to pass credentials and I still got the same error, so not sure what is going on here.
    First one, not really sure what is causing the error yet.

    Wondering if you have to pass credentials when calling the rest services, and if so, how did you accomplish this?
    Also, I know its s big ask, but wondering if you would mind sharing the code you created to call the rest api of uDeploy. Working with samples that work is much better than going in blind.

    Thanks up front for any help provided

  2. First things first, let’s make using the REST API easier, that is if you are using Java. If you open up one of the uDeploy-* plugins (i.e. uDeploy-Environment), there is a jar file in the lib directory called uDeployRestClient.jar. This jar file encapsulates many of the common uDeploy REST calls and takes care of the process of calling the REST url with proper authentication.

    You instantiate a new rest client like this:

    UDRestClient udclient = new UDRestClient(url, clientUser, clientPassword);

    You can then call any of its public methods like this one to create a new application as an example:

    UUID appID = udclient.createApplication(Str_appName, Str_appDescription, Str_notificationSchem, bool_enforceCompleteSnapshots);

    1. Unfortunately unless I have to use Java, I don’t. Just a preference. 😉
      Here is working version of this in C# using the RestSharp library.

      NOTE: I had used your advice and use Chrome tools to get the format of the JSON message and keys that were being passed. Once I had this it was a matter of getting the right format for serialization (note list of dictionary below).
      Also have to use authentication and HTTPS override (not in code below) to get working.

      You sent me down the right path, just needed to complete in a different language.

      var client = new RestClient();
      client.BaseUrl = “http://ipaddress:port”;
      client.Authenticator = new HttpBasicAuthenticator(“user”, “pass”);

      var versionList = new Dictionary();
      versionList.Add(“versionSelector”, “latestVersion”);
      versionList.Add(“componentId”, “component_UUID”);

      var propertiesList = new Dictionary();

      var request = new RestRequest(Method.PUT);
      request.RequestFormat = DataFormat.Json;
      request.Resource = “rest/deploy/application/application_UUID/runProcess”;

      applicationId = “application_UUID”,
      applicationProcessId = “applicationProcess_UUID”,
      description = “”,
      environmentId = “environment_UUID”,
      onlyChanged = “false”,
      properties = propertiesList,
      scheduleCheckbox = “false”,
      snapshotId = “”,
      versions = new List<Dictionary> {versionList}

      IRestResponse response = client.Execute(request);

  3. Hi,

    I have a question, Not sure if it is exactly related to the abovem but more to the integrartion with th Udeploy.
    How ca i invoke an executable JAR file ebbedded with a udeploy process as an action?

    Thank a lot i advance!

  4. Hi,
    I have a question not exactly about the topic but related – I would be happy if you could assist.
    How can I create a Plugin integrated with the UDeploy that executes an executable JAR file?
    Or – with out a plugin – add an action that does this operation?

    Thanks in advance,

  5. Do you have the java source? You could easily call a java method within a plugin. Almost all of the downloadable plugins do this. If not, then you could call the executable jar file via java with something like this that I found via Google:

    Runtime re = Runtime.getRuntime();
    BufferedReader output;
    cmd = re.exec(“java -jar MyFile.jar” + argument);
    output = new BufferedReader(new InputStreamReader(cmd.getInputStream()));
    } catch (IOException ioe){
    String resultOutput = output.readLine();

  6. First, Thanks Darell for your quick response!
    I do have the java code… I misunderstand how do I call a java method with the plugin?
    What kind of a plugin should I create?
    I sa there are various of plugins while there is a Shell option – Do you refer to that one?
    Can oyu please refer me to an additional data regarding the way I create a plugin that invokes the java method\jar integrating with the UDeploy?

    Thanks again for your kind help,

  7. I you look at any of the downloadable plugins, each plugin step is typically implemented using a Groovy script. You can essentially treat a Groovy script like java and put an import statement at the beginning, for example:

    import javax.mail.*;

    Then in the Groovy script you can create objects and use them like you would any other Java object, for example:

    Session lSession = Session.getDefaultInstance(mprops,null);
    MimeMessage msg = new MimeMessage(lSession);

    You would include the jar file in the lib directory of the plugin and make sure that you add these jars to the classpath of the plugin via the element in the plugin.xml file, like this:

    There are materials on building plugins if you are needing that knowledge.

  8. HI Darrell,

    Need help on uDeploy Restart Rest API. once the agent goes down, the rest API to restart the agent is not working. Is there any way to start the agent without manually connecting to host and doing it.


  9. Hi,
    I’m trying to get the history of all past deployments for an environment. From the wadl file, it seemed like a valid query, which allows a GET at this path – /rest/deploy/applicationProcessRequest/table. I’m using HttpBuilder
    custom library to make the REST calls. I captured the REST call made by my web browser for this purpose and the parameters passed in the query is following.


    But I’m unable to get this working. Groovy is complaining about parameter values in saying environment property does not exist (groovy.lang.MissingPropertyException). Also it is asking me to enclose complex
    parameters in parenthesis, which I’m guessing are the parameter names with underscore above. I did that and that particular error seemed to go away. But I’m stuck with the filterFields parameter value. It looks like they are using as parameter value to further reference the environment id inside the query even though I’m passing it in another parameter. Any help will be greatly appreciated.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s