Overview

Edit online

API v2 is a read-only REST-like API which lets you query data in your Targetprocess account.

Note: APIv2 is not a replacement of APIv1 Both versions of API co-exist and serve different purposes. APIv1 provides CRUD access to data. It has basic support for filtering and querying data. APIv2 provides read-only access to data. It has advanced support for filtering and querying data.

# Url format

/api/v2/{entity}/{id}?
where={where}&select={select}&result={result}&
take={take}&skip={skip}&orderBy={orderby}&
callback={callback}&filter={filter}
  • {entity} - entity type name in single case (Userstory, Bug) - see here for the list of available entity types
  • {id} - optional entity id. If specified, the response will contain only one item in {items} collection
  • {where} - filter expression over collection of entities
  • {select} - select projection.
  • {result} - final expression, used for aggregations' calculation on root entity.
  • {skip}, {take} - paging parameters, how many entities skip and take. If the result contains more entities, the response will have fields "next" or/and "prev" links to another pages.
  • {orderBy} - orderings
  • {callback} - JSONP callback
  • {filter} - a DSL Filter or Simple Filter like on boards.

    filter

    and where clauses are combined with and operator.

Also, you can add following flags to query string to modify output:

  • prettify - to prettify response json with spaces and new lines
  • isoDate - to get the dates in ISO 8601 format

Selectors

*** selector = expression \| objectExpression objectExpression = { namedSelectorList } namedSelectorList = namedSelector [,namedSelectorList ] namedSelector = field \| _name_:_expression_ \| functionCall functionCall = A call to Enumerable methods (see below) expression = field \| dlinqExpression field = Any field of a referenced entity (get from here) or projected object dlinqExpression = A valid .NET expression with some extensions (learn more) *** Every objectExpresssion will be represented as JSON object with given properties calculated from namedSelectors. For instance: https://md5.tpondemand.com/api/v2/UserStory?select={id,storyName:name,project:{project.id,project.name},tasks.count()} 
{
  "next": "http://md5.tpondemand.com/api/v2/UserStory?where=&select={id,storyName:name,project:{project.id,project.name},tasks.count()}&take=25&skip=25",
  "items": ___PROTECTED_12___

.NET Expressions

API v2 uses LINQ expression parser that use syntax that is very close to standard .NET syntax. More information: ___PROTECTED_13___

Filtering expressions

Filtering expressions should be valid ___PROTECTED_14___ that return true or false. You use these expressions in ___PROTECTED_29___ conditions. You can use identifier 'it' to reference the parameter of a filter. For example, I want list of all efforts greater than 5: 
/api/v2/Project?select={id,name,efforts:userStories.Select(effort).Where(it>5)}
{
      "id": 35923,
      "name": "Articles",
      "efforts": [
        10.0000,
        21.0000
      ]
    },
    {
      "id": 70163,
      "name": "Astroport",
      "efforts": [
        
      ]
    },
    {
      "id": 53775,
      "name": "AVM: CFO",
      "efforts": [
        9.5000
      ]
    },

Filters

Parameter named filter supports provision of a DSL Filter or Simple Filter like on boards. filter and where clauses are combined with and operator. 
/api/v2/request?filter=?AssignedUser.Where(it is Me)

Ordering

A parameter named orderBy sorts results in ascending or descending order. Ascending is the default option. To specify the order, you should place 'asc' or 'desc' after the selector. To enable additional sort criteria to sort a sequence, you can enumerate them using commas. For example, you can sort user stories descending by effort and then ascending by name: 
/api/v2/userstory?select={id,name,effort}&orderBy=effort desc,name)
[
	{
		"id": 72903,
		"name": "Defiant",
		"effort": 120
	},
	{
		"id": 86582,
		"name": "Nova",
		"effort": 50
	},
	{
		"id": 71004,
		"name": "Rigel",
		"effort": 20
	},
	{
		"id": 94066,
		"name": "Springfield",
		"effort": 20
	}
]
Collections can also be ordered in ascending or descending order. The default sorting of collection items is descending by Id. To have custom order, use orderBy() or orderByDescending() 
/api/v2/portfolioepic?select={id,name,epics:epics.orderByDescending(name).select(name)}
/api/v2/portfolioepic?select={id,name,epics:epics.orderBy(name).select(name)}

Response format

Response is JSON object with requested collection in items field. For instance: 
{
  "next": "/api/v2/UserStory?where=&select={id,name,endDate:(endDate-StartDAte).TotalDays}&take=25&skip=25&type=UserStory",
  "items": [
    {
      "id": 93110,
      "name": "Widgets API documentation"
    }
  ]
}
All fields are in camelCase, all null values are omitted.

Advanced Examples