REST API Getting Started
/api/v1/UserStories?include=[Name]&append=[Tasks-Count]&format=json&skip=25&where=EntityState.Name%20eq%20'Done'
Introduction
REST API allows to quickly extract data from TargetProcess. It can be easily used for any programming language and development platform. See more info on REST API in this 3 minute overview.
Authentication
TargetProcess REST API could use basic authentication. To use it, you need to send Authorization: Basic with every request. For example, if you want to be authenticated as admin:admin (login:password), you should send the following request:
GET targetprocess/api/v1/UserStories/ HTTP/1.1 Host: localhost Authorization: Basic YWRtaW46YWRtaW4=
YWRtaW46YWRtaW4= key is a Base64 encoded login and password values for admin:admin.
You can generate such a key online or use a special function in your programming language.
For example, in .NET it will look like that:
var webClient = new WebClient();
webClient.Credentials = new NetworkCredential("admin", "admin");
To consume REST service from Ruby, you may use HTTParty gem.
class UserStoryResource
include HTTParty
base_uri 'localhost'
format :xml
def initialize(u, p)
@auth = {:username => u, :password => p}
end
def all_stories(options={})
options.merge!({:basic_auth => @auth})
self.class.get("/targetprocess/api/v1/UserStories/", options)
end
end
...
storyResource = UserStoryResource.new('admin', 'admin')
stories = storyResource.all_stories
Get All User Stories
You can get various entities like User Stories, Bugs, Tasks, Iterations, Releases, Test Cases, etc. Check Reference documentation for more details.
To get a list of all User Stories just send GET request
http://localhost/targetprocess/api/v1/Userstories/
Response in XML format looks like
<UserStories Next="http://localhost/TargetProcess/api/v1/UserStories/?take=25&skip=25"> <UserStory Id="196" Name="Set Due Date"> <!-- ... --> </UserStory> <UserStory Id="192" Name="Make Task Important"> <!-- ... --> </UserStory> </UserStories>
Get All User Stories for Specific Projects
To get User Stories for a specific project you need to operate with Context. For example, to retrieve Context for projects with id = 1 and id = 88 you need to send this request:
http://localhost/targetprocess/api/v1/Context/?ids=1,88
Response contains Acid that should be used to filter user stories by selected projects.
<Context Acid="5183C75C9C20036C59F25256D20BCE95"> <!-- ... --> </Context>
Then you need to send a request like
http://localhost/targetprocess/api/v1/Userstories/?acid=5183C75C9C20036C59F25256D20BCE95
Get Specific Fields (partial get)
You can get user stories with specified fields only. Thus you have less traffic between TargetProcess application and this improves the overall performance. For example, we can request a list of User Stories with Name, Effort and Description fields only.
http://localhost/targetprocess/api/v1/Userstories/?include=[Name, Effort, Description]
Response looks like
<UserStories Next="http://localhost/TargetProcess/api/v1/UserStories/?include=[Name, Effort, Description]&take=25&skip=25"> <UserStory Id="196" Name="Set Due Date"> <Effort>27.0000</Effort> <Description>Need to process Due Date as well</Description> </UserStory> <UserStory Id="192" Name="Make Task Important"> <Effort>41.0000</Effort> <Description nil="true"/> </UserStory> </UserStories>
Get Appended Fields
You can get more information about User Story in a single request. For example, you can retrieve Tasks count and Bugs count for User Story.
http://localhost/targetprocess/api/v1/UserStories/?include=[Name]&append=[Bugs-Count,Tasks-Count]
<UserStories Next="http://localhost/TargetProcess/api/v1/UserStories/?include=[Name, Effort, Description]&take=25&skip=25"> <UserStory Id="196" Name="Set Due Date"> <Bugs-Count>0</Bugs-Count> <Tasks-Count>3</Tasks-Count> </UserStory> <UserStory Id="192" Name="Make Task Important"> <Bugs-Count>10</Bugs-Count> <Tasks-Count>0</Tasks-Count> </UserStory> </UserStories>
Get Excluding Some Fields
You can exclude some fields if you don't need them to have a lighter response. For example, if you don't need the Description field, you should send request like
http://localhost/targetprocess/api/v1/UserStories/?exclude=[Description]
Context
Context includes information on selected projects and processes. Process contains Terms, Practices and Custom Fields. If you want to build a UI client and show correct Terms and Custom fields, you'll have to use Context.
For example, to get context for entity with id = 1424 you should send request
http://localhost/targetprocess/api/v1/Context/?ids=1424
<Context Acid="5183C75C9C20036C59F25256D20BCE95">
<Edition>Pro</Edition>
<LoggedUser Id="316">
<FirstName>Administrator</FirstName>
<LastName>Administrator</LastName>
<Email>admin@nonexistingemail.com</Email>
<IsActive>true</IsActive>
<IsAdministrator>true</IsAdministrator>
</LoggedUser>
<Culture Name="en-US" TimePattern="g:i A" ShortDateFormat="M/d/yyyy" LongDateFormat="dddd, MMMM dd, yyyy" DecimalSeparator="." />
<SelectedProjects>
<ProjectInfo Id="375" Name="TargetProcess">
<Process Id="1" Name="All Practices" />
<Program nil="true" />
</ProjectInfo>
</SelectedProjects>
<Processes>
<ProcessInfo Id="1" Name="All Practices">
<Terms>
<Term Name="Features">
<Value>Epics</Value>
</Term>
<Term Name="Feature Big Icon Text">
<Value>Epic</Value>
</Term>
<Term Name="Feature Small Icon Text">
<Value>E</Value>
</Term>
</Terms>
<Practices>
<Practice Name="Planning">
<EffortPoints>Hour</EffortPoints>
<IsStoryEffortEqualsSumTasksEffort>false</IsStoryEffortEqualsSumTasksEffort>
</Practice>
<Practice Name="Time Tracking">
<IsCloseAssignableIfZeroTimeRemaining>false</IsCloseAssignableIfZeroTimeRemaining>
<IsTimeDescriptionFieldVisible>true</IsTimeDescriptionFieldVisible>
<IsTimeDescriptionRequired>true</IsTimeDescriptionRequired>
<IsRequiredShowRoleDropDown>false</IsRequiredShowRoleDropDown>
</Practice>
<Practice Name="Bug Tracking" />
<Practice Name="Requirements" />
<Practice Name="Test Cases" />
<Practice Name="Source Control" />
<Practice Name="Help Desk" />
<Practice Name="Iterations" />
</Practices>
<CustomFields>
<CustomFieldInfo Name="Custom description">
<EntityKind>UserStory</EntityKind>
<Type>Text</Type>
<Required>false</Required>
<Listed>false</Listed>
</CustomFieldInfo>
</CustomFields>
</ProcessInfo>
</Processes>
</Context>
Summary
Here is the list of common requestshttp://localhost/targetprocess/api/v1/Userstories/ http://localhost/targetprocess/api/v1/Userstories/56 http://localhost/targetprocess/api/v1/Userstories/56/Tasks http://localhost/targetprocess/api/v1/Context/?ids=1,88 http://localhost/targetprocess/api/v1/Userstories/?acid=2BC56B945886CD6CF74DE5BFB8D49FD9 http://localhost/targetprocess/api/v1/Tasks/?include=[Name, Effort, Description] http://localhost/targetprocess/api/v1/Releases/?include=[Name]&append=[Iterations-Count] http://localhost/targetprocess/api/v1/Projects/?exclude=[Description]
