User Guide

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.)

Download

Full API documentation

Web Services API documentation

Usage

Create a new project in Visual Studio and add a reference to the Rally.RestApi.dll library downloaded above:

Set your Project Target Framework to .NET Framework 4:

Instantiate a new RallyRestApi:

RallyRestApi restApi = **new** RallyRestApi("[email protected]", "password",

  "https://rally1.rallydev.com", "1.40");

The parameters for [RallyRestApi](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_RallyRestApi.htm) are as follows:

Parameter	Description	Example
userName*	The username to connect to Rally with.	"[email protected]"
password*	The password to connect to Rally with.	"password"
server	The Rally server to connect to. Default is https://rally1.rallydev.com	"https://rally1.rallydev.com"
WSAPI version	The Web Services API version to use. Default is v2.0	"1.40"

  * = required parameter

Public Methods

RallyRestApi exposes the following public methods:

Query

• Parameters: Request request*
•   * = required parameter
• Description: Search Rally for items matching the specified query. Returns a QueryResultobject containing the results of the request.
• Example:

// Build request
Request request = new Request("defect"); 
request.Fetch = new List<string>() {
	"Name","Description","FormattedID"};

request.Query = new Query("Name", Query.Operator.Equals, "My Defect").And(new Query("State", Query.Operator.Equals, "Submitted"));

// Make request and process results 
QueryResult queryResult = restApi.Query(request); 
foreach (var result in queryResult.Results) { 
	string itemName = result["Name"];
}

• Example Request for Portfolio Items:

// Build Portfolio Item Request
Request request = new Request("PortfolioItem/Initiative");
request.Fetch = new List<string>() {
	"Name","Description","FormattedID"};

GetByReference

• Parameters: string ref*, params string[] fetchFields
•   * = required parameter
• Description: Retrieve the Rally object represented by the specified ref. If fetchFields is specified those fields will be included in the returned object. Returns the resulting DynamicJsonObject.
• Example:

DynamicJsonObject item = restApi.GetByReference("https://preview.rallydev.com/slm/webservice/1.40/defect/12345.js", "Name", "FormattedID");
string itemName = item["Name"];

GetByReference

• Parameters: string type*, long oid*, params string[] fetchFields
•   * = required parameter
• Description: Overload of GetByReference using type and object id instead of a reference. If fetchFields is specified those fields will be included in the returned object. Returns the resulting DynamicJsonObject.
• Example:

DynamicJsonObject item = restApi.GetByReference("defect", 12345, "Name", "FormattedID");
string itemName = item["Name"];
string itemFormattedID = item["FormattedID"];

Create

• Parameters: string reference*, string type*, DynamicJsonObject object*
•   * = required parameter
• Description: Create an object of the specified type with the specified data in Rally. Returns a CreateResult object with the results of the request.
• Example:

String workspaceRef = "/workspace/12345678910"; DynamicJsonObject toCreate = new DynamicJsonObject();
toCreate["Name"] = "My Defect";
CreateResult createResult = restApi.Create(workspaceRef,"defect", toCreate);

Update

• Parameters: string reference*, DynamicJsonObject data*
•   * = required parameter
• Description: Update the specified item in Rally. Returns an OperationResult object with the results of the request.
• Example:

DynamicJsonObject toUpdate = new DynamicJsonObject(); 
toUpdate["Description"] = "This is my defect."; 
OperationResult updateResult = restApi.Update("https://preview.rallydev.com/slm/webservice/1.40/defect/12345.js", toUpdate);

Update (Overloaded)

• Parameters: string type*, long oid*, DynamicJsonObject data*

•   * = required parameter

• Description: Overload of Update using type and object id instead of a reference. Update the specified item in Rally. Returns an OperationResult object with the results of the request.

• Example:

DynamicJsonObject toUpdate = new DynamicJsonObject();
toUpdate["Description"] = "This is my defect.";
OperationResult updateResult = restApi.Update("defect", 12345L, toUpdate);

Delete

• Parameters: string reference*, string reference*

•   * = required parameter

• Description: Delete the specified object in Rally. Returns an OperationResult object with the results of the request. object with the results of the request.

• Example:

String workspaceRef="/workspace/12345678910";
String objectRef="/defect/12345678912";
OperationResult deleteResult = restApi.Delete(workspaceRef, objectRef);

Delete (Overloaded)

• Parameters: string reference*, string type*, long oid*
•   * = required parameter
• Description: Overload of Delete using type and object id instead of a reference. Delete the specified object in Rally. Returns an OperationResult object with the results of the request.

• Example:

String workspaceRef="/workspace/12345678910";
Long objectID=12345678912L;
String itemType="Defect";
OperationResult deleteResult = restApi.Delete(workspaceRef, itemType objectID);

GetAllowedAttributeValues

• Parameters: string type*, string attribute*
•   * = required parameter
• Description: Returns a DynamicJsonObject containing the allowed values for the specified type and attribute.
• Example:

DynamicJsonObject allowedValues = restApi.GetAllowedAttributeValues("defect", "severity");

GetAttributesByType

• Parameters: string typeName*
•   * = required parameter
• Description: Returns a QueryResult object containing the attribute definitions for the specified type.
• Example:

DynamicJsonObject allowedValues = restApi.GetAllowedAttributeValues("defect", "severity");

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:

   {
	configuration:{
        system:{
            value:undefined,
            diagnostics:{
                trace:{
                    autoflush:'true',
                    indentsize:4,
                    listeners:{
                        add:{
							name:'requestResponseLogger",
							type="System.Diagnostics.TextWriterTraceListener',
							initializedata: 'RallyRestApi.log',
                            filter:{
								type:'System.Diagnostics.EventTypeFilter',
                                initializedata:'Information'
                            }
                        },
                        remove:{
                            name:'Default'
                        }
                    }
                }
            }
        }
    }
}

Example

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

//Initialize the REST API
RallyRestApi restApi = new RallyRestApi("username", "password", "https://rally1.rallydev.com", "1.40");

//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, "Name");
string name = item["Name"];

//Query for items
Request request = new Request("defect");
request.Fetch = new List() {
		"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
  string formattedID = result["FormattedID"];
}

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