REST Services

REST is a loose set of guidelines for doing web services over HTTP. It uses HTTP methods (GET, POST, and so on) as part of the request. Each resource is exposed as an endpoint represented by a URL. For example, to fetch a specific defect a URL is constructed with the GET method that accesses the defect endpoint.

REST Operation HTTP Method
Read object GET
Create object POST or PUT
Update object POST
Fetch or query object GET
Delete object DELETE

JSON is the format for exchanging data through the REST API. To create a defect, create a file representing the defect and send that document (using the HTTP PUT method) to the defect URL endpoint. The REST URL for each resource is documented under Object Model in the navigation pane on the left.

Use curl to call the REST API

Curl is a popular command line HTTP client that has been ported to a large number of operating systems. Curl supports all the HTTP methods used by the CA Agile Central REST API. The examples below illustrate how to exercise the CA Agile Central REST API using curl commands. Filename is the name of the file to send to the server. All REST API calls require HTTP authentication.

    GET
    curl -u 'username:passwordurl
    PUT
    curl -u 'username:password' -T filename url
    POST (Encoding is set to text/javascript (JSON). Charset is optional and must match encoding used if present.)
    curl -u 'username:password' -H 'Content-Type: text/javascript;charset=utf-8' -d @filename url
    DELETE
    curl -u 'username:password' -X delete url

A simple object browser

The REST API combined with an XSL stylesheet creates a generic object browser. The CA Agile Central object model can be traversed starting at the URL below (Subscription → Workspace → Project → ...)
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/subscription

REST JSON Services

CA Agile Central's Web Services interface supports JSON (JavaScript Object Notation) as an encoding format for the REST API. JSON is an efficient encoding that is structurally similar to XML but more compact. JSON is ideal for JavaScript clients because it uses native JavaScript object encoding.

An object in JSON is surrounded by curly braces containing key/value pairs in a comma-separated list. Arrays are a comma-separated lists of values surrounded by square brackets.

A simple object with string, boolean, and number properties:

 { "Name": "bar", "Blocked": false, "Estimate": 12.7 }

An array of strings:

 [ "foo", "bar", "baz" ]

Object properties in JSON begin with an underscore "_". The outer-most object is encoded as a key/value pair where the key is the object type and the value is a list of properties surrounded by curly braces:

  
{ "Defect":     
	{
       "_rallyAPIMajor": "2",
       "_rallyAPIMinor": "0",       
       "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/defect/56176",       
       "_refObjectName": "This is the defect name",       
       "_type": "Defect",       
       "CreationDate", "2007-08-02T13:55:48.757Z",       
       "ObjectID": 56176,       
       "Name": "This is the defect name",       
       "FormattedID": "D57",       
       "LastUpdateDate", "2007-08-02T13:55:48.757Z",       
       "Project": {
            "_rallyAPIMajor": "2",
            "_rallyAPIMinor": "0",         
            "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/17986",         
            "_refObjectName": "Project 1",         
            "_type": "Project"      
        },       
        "SubmittedBy": "jhehr@rallydev.com",       
        "Duplicates": [         
        	{          
            	"_rallyAPIMajor": "2",          
                "_rallyAPIMinor": "0",           
                "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/defect/64032",           
                "_refObjectName": "Duplicate 1",           
                "_type": "Defect"         
             },         
             {          
             	"_rallyAPIMajor": "2",         
                "_rallyAPIMinor": "0",           
                "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/75760",           
                "_refObjectName": "Duplicate 2",           
                "_type": "Defect"         
             },       
         ]     
     }   
 }

The example above shows an object with an internal object reference to the defect's project:

"Project": "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/project/17986"

And an array of object references to the defect's duplicates:

"Duplicates": [ ... ]

An object reference, _ref, is a reference to the object and must be followed to fetch the full object. Notice that the outer object, the defect, is really a single key/value pair with a key of defect and the inner object references are the body portion of the object.

In this example, the following javascript code:

  var response = { ... JSON code from above ... }; 

Would enable access to properties as follows:

 // outer defect name   
 var name = response.Defect.Name;    
 
 // project ref URI   
 var projectRef = response.Defect.Project._ref;    
 
 // second duplicate ref URI   
 var dupeDefectRef = response.Defect.Duplicates[1]._ref; 

Use JSONP

CA Agile Central supports JSONP. It is used to wrap the JSON response in a JavaScript method call. If you specify jsonp=callback_function in the URL, the response will be as follows:

  callback_function(... JSON code from above ...)

This can be used in a JavaScript script as illustrated below:

  <script type="text/javascript"     src="https://rally1.rallydev.com/slm/webservice/v2.0/defect?query=query_string&jsonp=var%20response%20%3D"></script>

"jsonp" is set to "var%20response%20%3D". query_string is a valid query string. Including this script in an HTML page will cause a JavaScript object named "response" to be initialized with the query response. That object is then available in the JavaScript script in that page. For an example of this, click on one of the object types in the left-side navigation and run a query after checking the Beautified JSON output checkbox.

 

Collections

Collection elements contain multiple items. An example of a collection element is Artifact.Tags.

Collection references

Collection values are returned as an object with a count and a reference. The reference URL will have the format: TypeDefinitionName/ObjectID/CollectionElementName. For example, the Defect.Tags element is rendered with the following json:

{    
	"_rallyAPIMajor": "2",    
    "_rallyAPIMinor": "0",     
    "Name": "My Defect",     
    "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/defect/52774",     
    "Tags": {        
    	"_rallyAPIMajor": "2",        
        "_rallyAPIMinor": "0",         
        "Count": 2,         
        "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/defect/52774/tags"     
     } 
}

Get collection members

Collection references can be queried with a GET request to return an array of collection members. An example response from: https://rally1.rallydev.com/slm/webservice/v2.0/defect/52774/tags:

{     
	"QueryResult": {        
    	"_rallyAPIMajor": "2",        
        "_rallyAPIMinor": "0",         
        "TotalResultCount": 2,         
        "StartIndex": 1,         
        "PageSize": 20,         
        "Results": [             
        	{                 
            	"_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/23498",                 
                "Name": "Tag 1"             
            },                 
            	"_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/58714",                 
                "Name": "Tag2"             
            }         
        ]     
     } 
}

Collection reference urls support the same query parameters as standard TypeDefinition endpoints including fetch, query, order, start, and pagesize.

Add collection members

Add items to Modifiable collections by sending a POST request to a collection reference URL with a body containing an array of items to add. Example payload to add two tags to a collection by a POST request to:  https://rally1.rallydev.com/slm/webservice/v2.0/defect/52774/tags/add?fetch=Name:

{     
	"CollectionItems": [         
    	{             
        	// Items that do not have a reference yet will be created             
            "Name": "New Tag"         
        },             
        	// Pass a reference to add an existing item to a collection             
            "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/58714"         
        }     
    ] 
}

The response of a successful POST request will contain an OperationResult with object references for the items added to the collection. The object references honor the fetch parameter on the add request:

{     
	"OperationResult": {        
    	"_rallyAPIMajor": "2",        
        "_rallyAPIMinor": "0",         
        "Errors": [],         
        "Warnings": [],         
        "Results": [             
        	{                
            	"_rallyAPIMajor": "2",               
                "_rallyAPIMinor": "0",                 
                "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/28292",                 
                "_objectVersion": "1",                 
                "Version": "1",                 
                "_refObjectName": "New Tag",                 
                "Name": "New Tag",                 
                "_type": "Tag"             
            },             
            {               
            	"_rallyAPIMajor": "2",                
                "_rallyAPIMinor": "0",                 
                "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/58714",                 
                "_objectVersion": "1",                 
                "Version": "1",                 
                "_refObjectName": "Old Tag",                 
                "Name": "Old Tag",                 
                "_type": "Tag"             
            }        
        ]     
    } 
 }

Remove collection members

Remove items from Modifiable collections by sending a POST request to a collection reference URL with a body containing an array of items to remove. Example payload to remove a tag from a collection by a POST request to https://rally1.rallydev.com/slm/webservice/v2.0/defect/52774/tags/remove:

{     
	"CollectionItems": [         
    	{             
        	// Pass a reference to remove an existing item from a collection             
            "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/tag/58714"         
        }     
     ] 
}

The response of a successful POST request will contain an OperationResult with collections for any errors or warnings:

{     
	"OperationResult": {        
    	"_rallyAPIMajor": "2",        
        "_rallyAPIMinor": "0",         
        "Errors": [],         
        "Warnings": []    
     } 
}

Get collection summaries

Summarize collections by suffixing a summarizable collection element name with the :summary keyword. The summary can optionally be grouped by one or more attributes by enclosing a semicolon-delimited list of summary groupable fields within square brackets. Some example fetch lists for collection summaries are:
Defects with tasks collection summarized:
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/defect?fetch=Tasks:summary&order=Rank

Defects with tasks collection summarized, grouped by state and owner:
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/defect?fetch=Tasks:summary[State;Owner]&order=Rank

The summary can can also contain nested groups by enclosing a semicolon-delimited list of summary groupable fields combined with a + symbol. 


Defects with Tasks collection summarized, grouped by a combination of state and blocked:
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/defect?fetch=Tasks:summary[State+Blocked]&order=Rank

Query by collection existence

Use collection attributes in queries to filter results to only those items with empty or non-empty collections.
Stories with no children:
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?query=(Children.ObjectID = null)

Defects with at least one tag:
JSON: https://rally1.rallydev.com/slm/webservice/v2.0/defect?query=(Tags.ObjectID != null)

Cross-site access

With JSONP

The CA Agile Central REST API supports JSONP for cross-site requests. It is used to wrap the JSON response in a JavaScript method call. If you specify jsonp=callback_function in the URL, the response will be as follows:

    
   callback_function(... JSON code from above ...) 

This can be used in a JavaScript script as illustrated below:

    <script type="text/javascript" src="https://rally1.rallydev.com/slm/webservice/v2.0/defect.js?query=query_string&jsonp=callBack"/> 
The parameter jsonp is set to callBack and the parameter query_string is set to a valid query string. Including this script in an HTML page will cause the response to be wrapped in the callBack function, which will then be executed. The wrapped object is available in the callBack function. For an example of this, click on one of the object types in the left-side navigation and run a query after checking the Beautified JSON output checkbox.

With CORS

In addition to JSON, the CA Agile Central REST API also supports CORS for cross-site requests. The withCredentials property must be used to pass the user's credentials from the client to the server.

The example below illustrates a JavaScript application getting a Theme artifact and displaying all of that object's contents in the console log.

    
 <script>        
 	var myRequest = new XMLHttpRequest();          
    myRequest.withCredentials = true;         
    myRequest.open('GET', 'https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/theme/91634');
    myRequest.onreadystatechange = function () {             
    	if (this.status == 200 && this.readyState == 4) {                 
        	console.log('response: ' + this.responseText);             
        }         
     };         
     myRequest.send();     
</script>

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.