rally api

Java Toolkit for Rally REST API
Print this topicEmail this topicSave as PDF
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.

Full API documentation
Web Services API documentation

Usage
Create a new Java 6 project in your favorite IDE and add rally-rest-api-1.0.jar to your classpath.
You will also need to add the following jars:

httpcore-4.1.4.jar
httpclient-4.1.3.jar
httpclient-cache-4.1.3.jar
commons-logging-1.1.1.jar
commons-codec-1.4.jar
gson-2.1.jar

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

The gson-2.1.jar file can be found in google-gson-2.1-release.zip on Google Code.
In your main method, instantiate a new RallyRestApi:

RallyRestApi restApi = new RallyRestApi(new URI("https://rally1.rallydev.com"), "[e-mail]", "password");

The parameters for RallyRestApi are as follows:
Parameter Description Example
server* The Rally server to connect to. "https://rally1.rallydev.com"
userName* The username to connect to Rally with. "[e-mail]"
password* The password to connect to Rally with. "password"
* = required parameter

Public Methods
RallyRestApi exposes the following public methods:
Method Name Parameters Description
create CreateRequest request* Create the object described by the request parameter. Returns a CreateResponse object containing the results of the request.

Example:

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

get GetRequest request* Retrieve the object described by the request parameter. Returns a GetResponse object containing the results of the request.

Example:

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

delete DeleteRequest request* Delete the object described by the request parameter. Returns a DeleteResponse object containing the results of the request.

Example:

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

query QueryRequest request* 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 QueryResponse object 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 String wsapiVersion* Specifies the version of Rally's web services API to use. Defaults to 1.33

Example:

 restApi.setWsapiVersion("1.29");

getWsapiVersion Gets the version of Rally's web services that the Toolkit is configured to use.

Example:

  String version = restApi.getWsapiVersion();

setApplicationName String name* Set the name of your application. This name can be whatever you wish, and is added to the request headers of any web service requests your application makes. We encourage you to set this value, as it helps track usage of the toolkit.

Example:

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

setApplicationVersion String version* Set the version of the application using the Java Toolkit. This version can be whatever you wish, and is added to the request headers of any web service requests your application makes.

Example:

 restApi.setApplicationVersion("1.1");

setApplicationVendor String vendor* Set the vendor of the application using the Java Toolkit. This name can be whatever you wish (usually your company name), and is added to the request headers of any web service requests your application makes.

Example:

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

setProxy java.net.URI proxy*
String userName
String password Set the proxy server to use, if you connect to Rally through a proxy server. By default, no proxy is configured. The userName and password parameters are optional, and are used if your proxy server requires authentication.

Example:

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

close Closes open connections and releases resources. You should always call this method before your application exits.

Example:

 restApi.close();

* = required parameter

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"), "[e-mail]", "password");
        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"), "[e-mail]", "password");
        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();
        }
    }
}

Download Code:
rally-rest-api-1.0.zip

附件中是rally api的jar可以下载...