Migrating from Rally API 1.43 to 2.0 - Object Model

Question

I have inherited some custom java code that uses the Rally Java API v1.43 to query Rally, create and update stories. As I understand it, we created Java classes for the Rally Object model using wsdl2java that is described Here. Our code heavily uses these classes throughout.

Now that I have to upgrade to Rally v2.0 API, I do not understand whether I can easily leverage the code we already have based on these concrete classes or if I need to re-write everything to directly work with the JSON returned from Rally using something like JsonObject, or generating the JSON payloads directly as described in the v2.0 API documentation.

I've found plenty of examples on how to do things with v2.0 REST API which might be helpful if I were starting from scratch. Is there a better way to transition from v1.43 to v2.0?

Thank you

Answer 1

There are two issues here:

1. Transitioning from SOAP to REST
2. Transitioning from from older versions of WS API to v2.0.

Transitioning from SOAP to REST:

Indeed we no longer support SOAP and xml, and there is no WSDL for v2.0.

There is no standard refactoring path: the old code that used SOAP interface needs to be re-written using REST interface, often from scratch. We have a Rally Java REST Toolkit, available in this github repository.

Transitioning from from older versions of WS API to v2.0:

As far as transition from 1.43 to v2.0, a main difference is in how collections are handled.

In v2.0 we removed the ability to return child collections in the same response for performance reasons. In v2.0 fetching a collection will return an object with the count and the url from which to get the collection data. AppSDK2rc1 works with v2.0 of WS API.

In the older versions of WS API certain fetch lists create a lot recursive calls, and all the collections included in the fetch make the call quite expensive. In WS API v2.0 this will not happen, since a separate call will have to be made in order to get objects of the collections.

The code fragments below are both REST examples, but show how to refactor code to upgrade to v2.0.

Let's say you want to retrieve Test Cases associated with the Test Set.

Instead of this (which works in 1.43 because the collection is returned):

int numberOfTestCases = testSetJsonObject.get("TestCases").getAsJsonArray().size();
if(numberOfTestCases>0) {
    for (int j=0;j<numberOfTestCases;j++) {
       System.out.println(testSetJsonObject.get("TestCases").getAsJsonArray().get(j).getAsJsonObject().get("FormattedID"));
    }
}

Do this:

//TestCases is an object with a Count and a ref to load the collection
int numberOfTestCases = testSetJsonObject.getAsJsonObject("TestCases").get("Count").getAsInt();

if(numberOfTestCases > 0) {
    QueryRequest testCaseRequest = new QueryRequest(testSetJsonObject.getAsJsonObject("TestCases"));
    testCaseRequest.setFetch(new Fetch("FormattedID"));
    //load the collection
    JsonArray testCases = restApi.query(testCaseRequest).getResults();
    for (int j=0;j<numberOfTestCases;j++){
        System.out.println(testCases.get(j).getAsJsonObject().get("FormattedID").getAsString());
    }
}

Another common difference is that in v.2.0 custom fields are prepended with c_. A custom KanabanState field is referenced in WS API v2.0 as c_KanbanState.

Finally, update and create requests in v2.0 requre an extra layer of authentication. However as long as you use Rally Java REST Toolkit, you do not need to be concerned about it. The tookit does it behind the scene, and you do not need to write the code that requests a security token and maintains the session.