Skip to content

User Guide

Jump to bottom Edit New page
Matt Harutun edited this page Jul 19, 2013 · 9 revisions

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:

alt text

Set your Project Target Framework to .NET Framework 4:

alt text

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

 "1.40"
  * = required parameter

Public Methods

RallyRestApi exposes the following public methods:

Method Name Parameters Description
[Query](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Query_1_e7c29648.htm) [Request](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_Request.htm) request* Search Rally for items matching the specified query. Returns a [QueryResult](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_Response_QueryResult.htm) object 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:** //Build Portfolio Item Request

Request request = new Request("PortfolioItem/Initiative");

request.Fetch = new List<string>()

    {

    "Name",

    "Description",

    "FormattedID",

    };
[GetByReference](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_GetByReference_2_f5a7332b.htm) string ref*, params string[] fetchFields 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](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm).
**Example:** DynamicJsonObject item =

restApi.GetByReference

("https://preview.rallydev.com/slm/webservice/1.40/defect/12345.js", "Name", "FormattedID");

string itemName = item["Name"];
[GetByReference](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_GetByReference_3_f5cd4999.htm) string type*, long oid*, params string[] fetchFields 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](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm).
**Example:**

<font face=Courier, Courier new, monospace>DynamicJsonObject item =

restApi.GetByReference("defect", 12345, "Name", "FormattedID");

string itemName = item["Name"];
[Create](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Create_2_39c5ba29.htm) string reference*, string type*, [DynamicJsonObject](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm) object* Create an object of the specified type with the specified data in Rally.

Returns a CreateResult object with the results of the request.

**Example:**

<font face=Courier, Courier new, monospace> String workspaceRef = "/workspace/12345678910";

DynamicJsonObject toCreate = new DynamicJsonObject();

toCreate["Name"] = "My Defect";

CreateResult createResult = restApi.Create(workspaceRef,"defect", toCreate);
[Update](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Update_2_39c5ba29.htm) string reference*, [DynamicJsonObject](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm) data* Update the specified item in Rally.

Returns an OperationResult object with the results of the request.
**Example:**

<font face=Courier, Courier new, monospace>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](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Update_3_024c7b0f.htm) string type*, long oid*, [DynamicJsonObject](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm) data* 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:**

<font face=Courier, Courier new, monospace>DynamicJsonObject toUpdate = new DynamicJsonObject();

toUpdate["Description"] = "This is my defect."; OperationResult updateResult = restApi.Update("defect", 12345L, toUpdate);
[Delete](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Delete_1_bb3a7a4f.htm) string reference*, string reference* Delete the specified object in Rally.

Returns an OperationResult object with the results of the request.
**Example:**

<font face=Courier, Courier new, monospace> String workspaceRef="/workspace/12345678910";

String objectRef="/defect/12345678912";

OperationResult deleteResult = restApi.Delete (workspaceRef, objectRef);
[Delete](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_Delete_2_a98329ad.htm) string reference*, string type*, long oid* 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:**

<font face=Courier, Courier new, monospace> String workspaceRef="/workspace/12345678910";

Long objectID=12345678912L;

String itemType="Defect";

OperationResult deleteResult = restApi.Delete (workspaceRef, itemType objectID);
[GetAllowedAttributeValues](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_GetAllowedAttributeValues_2_f3570541.htm) string type*, string attribute* Returns a [DynamicJsonObject](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_DynamicJsonObject.htm) containing the allowed values for the specified type and attribute.
**Example:**

<font face=Courier, Courier new, monospace>DynamicJsonObject allowedValues = restApi.GetAllowedAttributeValues("defect", "severity");
[GetAttributesByType](https://docs.rallydev.com/restapinet/html/M_Rally_RestApi_RallyRestApi_GetAttributesByType_1_bb3a7a4f.htm) string typeName* Returns a [QueryResult](https://docs.rallydev.com/restapinet/html/T_Rally_RestApi_Response_QueryResult.htm) object containing the attribute definitions for the specified type.

Note: typeName should be the Name of the type- not the ElementName.

Example: "Hierarchical Requirement" instead of "hierarchicalrequirement".
**Example:**

<font face=Courier, Courier new, monospace>QueryResult attributeDefs = restApi.GetAttributesByType("Defect");

  * = required parameter

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"\ntype="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);
Add a custom footer
Add a custom sidebar
Clone this wiki locally