Using Rest Objects

Introduction

All rally resources referenced by the API are of type RestObject, there only a few subclasses. In its initial form a RestObject is just a URL representing a resource. This URL is accessed using RestObject#ref. When more information is requested about the object, the API will read the content of that resource. This read is done lazily and transparently.

RestObject makes heavy use of #method_missing to achieve its dynamism. The XML for each resource is parsed into a nested Hash where the keys of the Hash are the Ruby-ized Element names of the XML, and the values of the hash are the string values of the elements, or other RestObjects (in the case of references between objects), or collections of both. This allows the API to respond to chained method invocations like:

  rally.user.subscription.workspaces.first.projects.first.iterations.first.name

• invoke the #user method on the api
• read the subscription object on that user
• get the workspace collection from the subscription (as an Array)
• with the first workspace, get the projects collections
• read the first project, and
• return the name of the first iteration.

Traversals across object references (RestObjects) cause a lazy read of that resource.

When establishing object relationships between objects, during create or update, they are done using RestObjects. For example, to associate a user story to a defect, you would use the ‘requirement’ association on defect to reference the User Story.

Rally’s API expects that the association will be passed in as an XML element containing the ref of the associated object. To the #update method RallyRestAPI will send:

   <Defect>
     <Requirement ref="https://rally1.rallydev.com/slm/webservices/UserStory/12345"/>
   </Defect>

when you say:

  defect.update(:requirement => user_story)

assuming, of course, you already have RestObjects representing a defect and user story.