Skip to content

User Guide

Jump to bottom Edit New page
krmorse edited this page Mar 16, 2016 · 18 revisions

##Introduction

The Java Toolkit for Rally REST API provides an intuitive Java API for accessing your Rally Data.

It provides a rich set of capabilities for querying, along with methods for creating, reading, updating, and deleting individual items.

Download

Full API documentation

Web Services API documentation

Setup

Create a new Java project in your favorite IDE.

Manual

Add rally-rest-api-2.2.1.jar appropriate to your version of JDK to your classpath.

You will also need to add the following jars:

  • httpcore-4.2.4.jar
  • httpclient-4.2.5.jar
  • commons-logging-1.1.1.jar
  • commons-codec-1.6.jar
  • gson-2.2.4.jar

All the jars except gson-2.1.jar can be found in httpcomponents-client-4.2.5-bin.zip in the archives for the Apache httpcomponents project.

The gson-2.2.4.jar file can be found in google-gson-2.2.4-release.zip on Google Code.

Managed (Maven)

Add the rally-rest-api dependency to your pom.xml:

<dependency>
    <groupId>com.rallydev.rest</groupId>
    <artifactId>rally-rest-api</artifactId>
    <version>2.2.1</version>
</dependency>

Usage

In your main method, instantiate a new [RallyRestApi] (https://rallytools.github.io/RallyRestToolkitForJava/com/rallydev/rest/RallyRestApi.html):

RallyRestApi restApi = new RallyRestApi(new URI("https://rally1.rallydev.com"), "_fad8f7HD348");

The parameters for [RallyRestApi](https://rallytools.github.io/RallyRestToolkitForJava/com/rallydev/rest/RallyRestApi.html) are as follows:

Parameter Description Example
server* The Rally server to connect to. "https://rally1.rallydev.com"
apiKey* The API Key to connect to Rally with. "_fad8f7HD348"
  * = required parameter

Need help generating API Keys?

Public Methods

RallyRestApi exposes the following public methods:

Create

JsonObject newDefect = new JsonObject();
newDefect.addProperty("Name", "Test Defect");
CreateRequest createRequest = new CreateRequest("defect", newDefect);
CreateResponse createResponse = restApi.create(createRequest);

Get

GetRequest getRequest = new GetRequest("/defect/1234.js");
GetResponse getResponse = restApi.get(getRequest);

Update

JsonObject updatedDefect = new JsonObject();
updatedDefect.addProperty("State", "Fixed");
UpdateRequest updateRequest = new UpdateRequest("/defect/1234.js", updatedDefect);
UpdateResponse updateResponse = restApi.update(updateRequest);

Update Collection

JsonArray tagRefs = new JsonArray();
JsonObject tagRef = new JsonObject();
tagRef.addProperty("_ref", "/tag/12345");
tagRefs.add(tagRef);

CollectionUpdateRequest defectTagCollectionAddRequest = new CollectionUpdateRequest("/defect/23456/tags", tagRefs, true);
storyTagCollectionAddRequest.setFetch(new Fetch("Name"));
CollectionUpdateResponse defectTagCollectionAddResponse = restApi.updateCollection(defectTagCollectionAddRequest);

Delete

DeleteRequest deleteRequest = new DeleteRequest("/defect/1234.js");
DeleteResponse deleteResponse = restApi.delete(deleteRequest);

Query

  • Method Name: com.rallydev.rest.RallyRestApi.query
  • Parameters: QueryRequest request*
  •   * = required parameter
  • Description: Query for objects matching the specified request. By default one page of data will be returned. Paging will automatically be performed if a limit is set on the request. Returns a QueryResponseobject containing the results of the request.
  • Example:
QueryRequest defectRequest = new QueryRequest("defect");

defectRequest.setFetch(new Fetch("FormattedID", "Name", "State", "Priority"));
defectRequest.setQueryFilter(new QueryFilter("State", "=", "Fixed").and(new QueryFilter("Priority", "=", "Resolve Immediately")));
defectRequest.setOrder("Priority ASC,FormattedID ASC");

defectRequest.setPageSize(25);
defectRequest.setLimit(100);

QueryResponse queryResponse = restApi.query(defectRequest);

setWsapiVersion

restApi.setWsapiVersion("v2.0");

getWsapiVersion

String version = restApi.getWsapiVersion();

setApplicationName

restApi.setApplicationName("Universal Rally Data Extractor");

setApplicationVersion

restApi.setApplicationVersion("1.1");

setApplicationVendor

restApi.setApplicationVendor("My Company, Inc.");

setProxy

restApi.setProxy(new URI("http://myproxy.mycompany.com"), "MyProxyUsername", "MyProxyPassword");

close

  • Method Name: com.rallydev.rest.RallyRestApi.close
  • Description: Closes open connections and releases resources. You should always call this method before your application exits.
  • Example:
restApi.close();

Examples

The following code illustrates how to create, read, update, and delete a defect using the RallyRestApi object.

import com.google.gson.JsonObject;
import com.rallydev.rest.RallyRestApi;
import com.rallydev.rest.request.CreateRequest;
import com.rallydev.rest.request.DeleteRequest;
import com.rallydev.rest.request.GetRequest;
import com.rallydev.rest.request.UpdateRequest;
import com.rallydev.rest.response.CreateResponse;
import com.rallydev.rest.response.DeleteResponse;
import com.rallydev.rest.response.GetResponse;
import com.rallydev.rest.response.UpdateResponse;
import com.rallydev.rest.util.Ref;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

public class CrudExample {

    public static void main(String[] args) throws URISyntaxException, IOException {

        //Create and configure a new instance of RallyRestApi
        RallyRestApi restApi = new RallyRestApi(new URI("https://rally1.rallydev.com"), "_fad8f7HD348");
        restApi.setApplicationName("CrudExample");

        try {

            //Create a defect
            System.out.println("Creating defect...");
            JsonObject newDefect = new JsonObject();
            newDefect.addProperty("Name", "Test Defect");
            CreateRequest createRequest = new CreateRequest("defect", newDefect);
            CreateResponse createResponse = restApi.create(createRequest);
            System.out.println(String.format("Created %s", createResponse.getObject().get("_ref").getAsString()));

            //Read defect
            String ref = Ref.getRelativeRef(createResponse.getObject().get("_ref").getAsString());
            System.out.println(String.format("\nReading defect %s...", ref));
            GetRequest getRequest = new GetRequest(ref);
            GetResponse getResponse = restApi.get(getRequest);
            JsonObject obj = getResponse.getObject();
            System.out.println(String.format("Read defect. Name = %s, State = %s",
                    obj.get("Name").getAsString(), obj.get("State").getAsString()));

            //Update defect
            System.out.println("\nUpdating defect state...");
            JsonObject updatedDefect = new JsonObject();
            updatedDefect.addProperty("State", "Fixed");
            UpdateRequest updateRequest = new UpdateRequest(ref, updatedDefect);
            UpdateResponse updateResponse = restApi.update(updateRequest);
            obj = updateResponse.getObject();
            System.out.println(String.format("Updated defect. State = %s", obj.get("State").getAsString()));

            //Delete defect
            System.out.println("\nDeleting defect...");
            DeleteRequest deleteRequest = new DeleteRequest(ref);
            DeleteResponse deleteResponse = restApi.delete(deleteRequest);
            if (deleteResponse.wasSuccessful()) {
                System.out.println("Deleted defect.");
            }

        } finally {
            //Release all resources
            restApi.close();
        }
    }
}

The following code illustrates how to query for the top 5 highest priority defects:

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.rallydev.rest.RallyRestApi;
import com.rallydev.rest.request.QueryRequest;
import com.rallydev.rest.response.QueryResponse;
import com.rallydev.rest.util.Fetch;
import com.rallydev.rest.util.QueryFilter;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

public class QueryExample {

    public static void main(String[] args) throws URISyntaxException, IOException {

        //Create and configure a new instance of RallyRestApi
        RallyRestApi restApi = new RallyRestApi(new URI("https://rally1.rallydev.com"), "_fad8f7HD348");
        restApi.setApplicationName("QueryExample");

        try {

            System.out.println("Querying for top 5 highest priority unfixed defects...");

            QueryRequest defects = new QueryRequest("defect");

            defects.setFetch(new Fetch("FormattedID", "Name", "State", "Priority"));
            defects.setQueryFilter(new QueryFilter("State", "<", "Fixed"));
            defects.setOrder("Priority ASC,FormattedID ASC");

            //Return up to 5, 1 per page
            defects.setPageSize(1);
            defects.setLimit(5);

            QueryResponse queryResponse = restApi.query(defects);
            if (queryResponse.wasSuccessful()) {
                System.out.println(String.format("\nTotal results: %d", queryResponse.getTotalResultCount()));
                System.out.println("Top 5:");
                for (JsonElement result : queryResponse.getResults()) {
                    JsonObject defect = result.getAsJsonObject();
                    System.out.println(String.format("\t%s - %s: Priority=%s, State=%s",
                            defect.get("FormattedID").getAsString(),
                            defect.get("Name").getAsString(),
                            defect.get("Priority").getAsString(),
                            defect.get("State").getAsString()));
                }
            } else {
                System.err.println("The following errors occurred: ");
                for (String err : queryResponse.getErrors()) {
                    System.err.println("\t" + err);
                }
            }

        } finally {
            //Release resources
            restApi.close();
        }
    }
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally