Use the Web Services API

The following topics can help you understand and use CA Agile Central's Web Services API:

Authorization

Security token

To ensure data is protected against cross-site request forgery, a security token is required to authorize requests that result in a data change:

  • PUT/POST – Create
  • POST – Update
  • DELETE – Delete

Note: When using any of the CA Agile Central REST Toolkits or the App SDK this will be automatically handled.

Get the security token

A GET request, which requires an HTTP Basic Authentication header, to the following endpoint provides the security token:

https://rally1.rallydev.com/slm/webservice/v2.0/security/authorize

An operation result of the following structure is returned from the endpoint:

  {     "OperationResult": {
          		"_rallyAPIMajor": "2",
                "_rallyAPIMinor": "0",
                "Errors": [ ],
                "Warnings": [ ],
                "SecurityToken":"<SECURITY_TOKEN>"     
          } 
    }

Use the security token

The security token needs to be added to POST, PUT, and DELETE requests as a parameter of key for authorization (the token should not be quoted):

https://rally1.rallydev.com/slm/webservice/v2.0/defect/create?key=<SECURITY_TOKEN>

If the token is not provided, an operation result result will be returned indicating an invalid key:

 {     
 	  "OperationResult":
              "_rallyAPIMajor": "2",
              "_rallyAPIMinor": "0",         
              "Errors": [             
              			"Not authorized to perform action: Invalid key"         
               ],         
               "Warnings": [ ]     
       } 
 }

User creation and management

Create users

The following code is an example of creating a user object in CA Agile Central using the Web Services API. Only subscription and workspace administrators are allowed to create users.

     
HTTP call:        
	POST https://rally1.rallydev.com/slm/webservice/v2.0/user/create      
    
Payload, set "Content-Type" header to text/plain:        
	{            
    	"User": {                
        	"EmailAddress": "janedeveloper@develop.com",                
            "FirstName": "Jane",                
            "LastName": "Developer",                
            "DisplayName": "Jane Developer",                
            "UserName": "janedeveloper@develop.com"            
         }        
    }  

After user creation, a password-reset email will be sent to the email address set as the user's login name. This newly created user will have Workspace User and Project Viewer permissions according to the subscription administrator's default workspace and project. If no default workspace or project is set, the first open project is chosen alphabetically. The workspace associated with that project is selected as the current default workspace.

Permission management for users

User permissions can be queried through the CA Agile Central Web Services API. The objects that define the permissions model are UserPermission (abstract), WorkspacePermission, and ProjectPermission.

To change user permissions, use the graphical applications in the CA Agile Central tools. UserPermission will be enhanced in the future to allow modification of user permissions. STILL CORRECT?

User custom fields

User custom fields can be queried and updated through the CA Agile Central Web Services API. User custom fields behave just like custom fields on artifacts like defect or task.

Custom field query example

If User has a custom field named CustomField, then querying for all users with the CustomField set to "foo" would be:

https://rally1.rallydev.com/slm/webservice/v2.0/Users?query=(CustomField = foo)

 

Project scoping

All artifacts are scoped to a project. This includes all requirements as well as card, task, iteration, and release objects. CA Agile Central supports multiple levels of project scoping. Versions 1.03 and earlier of the API supported a single parent project which could be specified using a null reference. This method will continue to work in version 1.03 and earlier using the null reference, so long as a single root project is in the hierarchy. If there is more than one root project, a non-null project reference must be specified.

The project attribute of a given object may be set to any project in your workspace.

Scoping within a query is controlled with two boolean parameters (projectScopeUp and projectScopeDown). These parameters control whether parent or child projects are included in the search space. When not specified, they default to the user's setting in the project picker. To guarantee consistent results, both should be specified.

Parent project selected,
projectScopeUp is true (or false),
projectScopeDown is true.
Parent project selected,
projectScopeUp is true (or false),
projectScopeDown is false.
Project A selected,
projectScopeUp is false,
projectScopeDown is false (or true).
Project A selected,
projectScopeUp is true,
projectScopeDown is false (or true).

Query results as RSS 2.0 feeds

Object queries can be returned as RSS 2.0 feeds. The name of the object is returned as the title of the item. The example below illustrates a URL that returns a list of open defects assigned to you sorted by priority and severity. (note /rss before the object type):

https://rally1.rallydev.com/slm/webservice/v2.0/rss/TypeName?title=FeedTitle&query=QueryString&...

In addition to the standard query parameters, the RSS endpoint includes:

    title
    The title the feed will return such as My Open Defects.

Some RSS feed examples are:

 

Schema endpoint

The schema endpoint is an optimization for discovering type definitions and attribute definitions. A request to the schema endpoint returns a JSON representation of all enabled type definitions and their metadata (such as attributes, allowed values, types, and so on). This endpoint is preferred over the TypeDefinition endpoint, which required multiple requests for type definitions and their attributes.

The schema responses are scoped to a given workspace. The schema can be requested by the workspace or project ObjectID. If the project ObjectID is provided, the service will look up the workspace for that project, but will reflect the visibility of attributes at the project level. There is an optional hash for the schema request. If it is not provided, the service will determine the hash and redirect the request internally. Requesting a hash that is no longer current will redirect to the current hash.

Responses have a TTL of one year and subsequent requests for a given schema can be returned by the browser cache.

Usage

Schema request by workspace:

https://rally1.rallydev.com/slm/schema/v2.0/workspace/<ObjectID>/<Hash>

Schema request by project (service discovers the workspace):

https://rally1.rallydev.com/slm/schema/v2.0/project/<ObjectID>/<Hash>

Object model metadata

The TypeDefinition collection on the workspace object provides the object model metadata. TypeDefinition can be queried to get this information.

For example, the following query will return the definition of the defect type:

https://rally1.rallydev.com/slm/webservice/v2.0/typedefinition?query=(Name = Defect)&fetch=true

Within the TypeDefinition, the ObjectID is returned. The ObjectID can be used to get the attribute definitions with the Attributes endpoint. For example:

https://rally1.rallydev.com/slm/webservice/v2.0/TypeDefinition/‹ObjectID›/Attributes

The Attributes endpoint returns the attribute definitions and allowed values for the default workspace if the workspace is not specified. The default workspace can be overridden with the workspace parameter.

Schema endpoint

The schema endpoint is preferred over the TypeDefinition endpoint, as it combines the type definitions and attributes into a single request by workspace or project.

Client-provided integration information

CA Agile Central collects the following non-proprietary and non-confidential information as optionally provided by the user. This information is used to understand usage patterns and improve CA Agile Central's products.

The information requested is:

  • Name: Integration name, such as Subversion Plugin.
  • Vendor: Integration vendor, such as CA Agile Central Software.
  • Version: Integration version, such as 2.01.
  • OS: Client operating system information, such as Linux 2.6.18-8.1.1.el5 amd64.
  • Platform: Various platform information, such as the JDK version or Ruby runtime version, such as Java 1.6.0_41.
  • Library: Library framework information, such as "CA Agile Central Ruby REST API" or Apache Axis 1.4.

Provide integration information through the REST API

The optional information is submitted in the HTTP header:
    X-CA Agile CentralIntegrationName
    X-CA Agile CentralIntegrationVendor
    X-CA Agile CentralIntegrationVersion
    X-CA Agile CentralIntegrationOS
    X-CA Agile CentralIntegrationPlatform
    X-CA Agile CentralIntegrationLibrary

Attributes

API responses have attributes that may be used for processing the elements in the response.

    _rallyAPIMajor
    The major version of the Web Services API. For example, the rallyAPIMajor of version v2.0 is 2.
    _rallyAPIMinor
    The minor version of the Web Services API. For example, the rallyAPIMinor of version v2.0 is 0.
    _ref
    If the element represents an object, such as a defect, this will be set to the URL for that object. It is the unique identifier for the object, which is used to update or delete the object.
    _refObjectName
    The name of the object.
    _refObjectUUID
    Global ID (UUID) of an object.
    _type
    The type of object, such as HierarchicalRequirement or Discussion.

FAQ

Where is user story?

A user story is not a native object; it is a special case of the hierarchical requirement object. The hierarchical requirement is more flexible than a predefined user story object. This was done to facilitate future product direction, such as user-defined labels for objects.

Why are iteration and release dates modified after setting them?

Iteration and release dates are shifted to either the start of the day or end of the day in the workspace's time zone.

Why are attributes of the type boolean never required?

A boolean is either true or false and implicitly required. Boolean attributes always display with required set to false. If you do not set a boolean attribute when creating an artifact, it will default to null which the application will interpret as false.

What is the API version named current?

Current was a pointer to the most recent version of the web service API, changing with every new release of the web service. Current was deprecated with version 1.17 of the API and should no longer be used.

API deprecation

CA Agile Central Software may, from time to time, modify, discontinue, or deprecate any APIs, Language-Specific Toolkits, and SDKs, but will use commercially reasonable efforts to support the previous version of any APIs, Toolkits or SDKs for one year – referred to as the deprecation period (except where doing so (i) would create a security threat or intellectual property issue, (ii) is financially or technically unfeasible, or (iii) is necessary to comply with applicable laws or governmental requests).

After the one year deprecation period expires for that product (API, Toolkit, SDK), it is no longer supported, maintained, or assumed to be in a state that is usable by the customer. CA Agile Central Software has the right to terminate versions where the deprecation period has expired. This deprecation policy will begin starting October 1, 2012 with the first set of APIs and toolkits being no longer supported on October 1, 2013.

Requests against deprecated and not supported versions of the API will return a warning indicating that the state is either Deprecated or Not Supported. Warnings are returned for collections on JSON and XML responses, but they will not be returned for XML responses if the request is against a specific artifact.

CA Agile Central reserves the right to modify this API deprecation policy at any time, in its sole discretion.

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.