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
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.
Then you need to send a request like
http://localhost/targetprocess/api/v1/Userstories/?acid=2BC56B945886CD6CF74DE5BFB8D49FD9
Filtering will be added to API in future, but so far there are no other ways to filter lists.
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
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]
Only collection counts are supported so far. Other operations can be added in the future.
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
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]
