Getting Started

/api/v1/

REST API v.1 allows you to quickly extract and modify data in Targetprocess. It can be easily used with any programming language and development platform. General principles of RESTful web services are described in Wikipedia here: Representational State Transfer

See more info on Targetprocess REST API in this 3 minute overview.

Authentication

Targetprocess REST API can 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 /api/v1/UserStories/ HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=

YWRtaW46YWRtaW4= key is a Base64 encoded login and password values for admin:admin. You can generate such key using online services or in PowerShell for e.g.:

$Text = 'admin:admin'
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
$EncodedText =[Convert]::ToBase64String($Bytes)
$EncodedText

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('admin:admin'))

[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('YWRtaW46YWRtaW4='))

When you encode a login:password pair, please make sure you don't have any extra spaces or carriage return / line break symbols at the beginning or end of the copy-pasted line.

You can also use a special function in your programming language.

For example, in .NET / C# it will look like this:

var webClient = new WebClient();
webClient.Credentials = new NetworkCredential("admin", "admin");

Check Authentication section for other authentication types, like Cookie and Token.

Get All User Stories

📘

You can get various entities like User Stories, Bugs, Tasks, Iterations, Releases, Test Cases, etc. Check our Reference documentation for more details.

To get a list of all User Stories just send a GET request

/api/v1/UserStories/

The response in XML format looks like

<UserStories Next="https://restapi.tpondemand.com/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

You can use Filters to pull only the stories you are interested in.
For example, to get stories from the Projects ID#1 and ID#2 you need to send this request:

/api/v1/userstories?where=Project.Id in (1,2)

Get Specific Fields (partial get)

You can get User Stories with specified fields only. Requiring less traffic with Targetprocess, pulling select information improves overall performance. For example, we can request a list of User Stories with Name, Effort and Description fields only.

/api/v1/Userstories/?include=[Name, Effort, Description]

Response looks like:

<UserStories Next="https://restapi.tpondemand.com/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

In a single API v.1 request you can perform common math operations over fields of entities in nested collections using appends. As a result you get calculated numeric values.

For example, you can retrieve the Tasks count and Bugs count for User Stories.

/api/v1/UserStories/?include=[Name]&append=[Bugs-Count,Tasks-Count]

Result:

<UserStories Next="https://restapi.tpondemand.com/api/v1/UserStories/?include=[Name]&append=[Bugs-Count,Tasks-Count]&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 shorter response. For example, if you don't need the Description field, you should send a request like

/api/v1/UserStories/?exclude=[Description]

Create entities

To create a resource, the resource representation (either xml or json depending on Content-Type header) should be POSTed to the collection URL

For example, to create a Project with XML, the following request could be used:

POST /api/v1/Projects HTTP/1.1
Content-Type: application/xml
 
<Project Name="Some Project"/>

Summary

See more examples and try it out live at Reference page.