Click or drag to resize
Rally.RestApi Namespace

This is the primary namespace for the Rally Rest API for DotNet.

Introduction

The Rally REST API for .NET provides an intuitive interface to your Rally Data. It supports querying items in addition to individual item creates, reads, updates and deletes. It is compatible with any .NET 4.0 language (C#, VB.NET, F#, etc.)

Adding the API to your Solution

Add a reference to the Rally.RestApi.dll library or libraries from a new or existing project. Your project must have a Project Target Framework of .NET Framework 4 or higher.
LibraryRequiredUsed For
Rally.RestApi.dllYesCommunication with Rally
Rally.RestApi.UiForWinforms.dllNoProvides a UI for Winforms applications
Rally.RestApi.UiForWpf.dllNoProvides a UI for WPF applications
Can be used by Winforms applications that need IDP based SSO

Sample Usage

This sample code snippet shows how the Rally Rest API can be used by a console application:

C#
string username = "paul@acme.com";
string password = "Just4Rally";
string serverUrl = "https://preview.rallydev.com";

// Initialize the REST API. You can specify a web service version if needed in the constructor.
RallyRestApi restApi = new RallyRestApi();
restApi.Authenticate(username, password, serverUrl, proxy: null, allowSSO: false);

//Create an item
DynamicJsonObject toCreate = new DynamicJsonObject();
toCreate["Name"] = "My Defect";
CreateResult createResult = restApi.Create("defect", toCreate);

//Update the item
DynamicJsonObject toUpdate = new DynamicJsonObject();
toUpdate["Description"] = "This is my defect.";
OperationResult updateResult = restApi.Update(createResult.Reference, toUpdate);

//Get the item
DynamicJsonObject item = restApi.GetByReference(createResult.Reference);

//Query for items
Request request = new Request("defect");
request.Fetch = new List<string>() { "Name", "Description", "FormattedID" };
request.Query = new Query("Name", Query.Operator.Equals, "My Defect");
QueryResult queryResult = restApi.Query(request);
foreach (var result in queryResult.Results)
{
  //Process item as needed
}

//Delete the item
OperationResult deleteResult = restApi.Delete(createResult.Reference);

Logging

The Rally REST API for .NET provides the ability to log all requests and responses to aid in troubleshooting. To enable this behavior simply configure one or more trace listeners at the Information level. Below is an example App.config which will enable this:
Example App.config
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <trace autoflush="true" indentsize="2">
      <listeners>
        <add name="RallyRestApiUiSample" type="System.Diagnostics.TextWriterTraceListener
          initializeData="RallyRestApiUiSample.log" />
        <remove name="Defaultlisteners>
    </trace>
  </system.diagnostics>
</configuration>

Upgrading from Rally Rest API 2.x

If you are upgrading from the 2.x series of the Rally Rest API for DotNet, the following major changes are known:

  • Reorganization of Namespaces - Moved many classes into sub-namespaces for better organization of code
  • Changes to Visibility - Many classes and methods had their visibility changed to make it easier to find the methods that a user should be calling, instead of internal helper functions.
  • Authenication sequence - Constructor no longer performs authentication
  • Reusable UI Layer - We added components for standardized login windows throughout all applications using the toolkit, including support for SSO
  • Exceptions - We added custom exceptions for Rally being unavailable (returning HTML error page), or JSON data being unable to be deserialized.
  • Code Comments - We greatly expanded on the code header comments that generate this help documentation.

This example shows the changes to authentication for a console application. For UI based applications, please see the documentation for the Rally.RestApi.UiForWpf Namespace for extended examples.

C#
// Old authentication in constructor
RallyRestApi restApi = new RallyRestApi("user@sandbox.com", "secret", "https://sandbox.rallydev.com", "v2.0");

// New authentication method
RallyRestApi restApi = new RallyRestApi(webServiceVersion: "v2.0");
restApi.Authenticate("user@sandbox.com", "secret", "https://sandbox.rallydev.com", allowSSO: false);
Classes
  Class Description
Public class Query
This class represents a filter for query operations.
Public class RallyRestApi
The main interface to the Rally REST API
Public class Ref
The Ref class contains a set of utility methods for working with refs.
Public class Request
Represents a request to be sent to Rally
Enumerations
  Enumeration Description
Public enumeration QueryOperator
The available query operators
Public enumeration RallyRestApiAuthenticationResult
Enumeration of the different authentication results that may occur.
Public enumeration RallyRestApiHeaderType
Enumeration of the valid HTTP headers that may be passed on REST requests