Targetprocess

The Targetprocess Developer Hub

Welcome to the Targetprocess developer hub. Here you'll find comprehensive guides and documentation to help you start working with Targetprocess as quickly as possible and support you if you get stuck. Let's jump right in!

Docs

Overview

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

Important notice

API v2 is primarily intended for internal usage and integration between various components of Targetprocess. You can use it for your own purposes but please keep in mind that unlike API v1 we don't provide any backwards or forwards compatibility guarantees of API v2 between different Targetprocess versions. It also may be changed at any moment without any notice to meet the new requirements of Targetprocess itself.

This all means that you play with API v2 at your own risk. Don't hold us responsible for any future damage. Consider using API v1 for more stable public surface.

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) or plural case (Userstories, Bugs) - 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 falgs 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": [
    {
      "id": 93114,
      "storyName": "Study Projectplace tool",
      "project": {
        "id": 37819,
        "name": "AVM: MKT_Backlog"
      },
      "count": 0
    },
    {
      "id": 93112,
      "storyName": "Briefly describe api v2",
      "project": {
        "id": 49105,
        "name": "TP3"
      },
      "count": 1
    },

If a name of the result filed is not defined, api V2 tries to inference the field name using a) field names (id -> id, project.id -> id), b) aggregation names (tasks.count() -> count), otherwise it will use name.

name should be a valid alphanumeric identifier: OK - id, camelCase, name1, name_with_underscore. Not OK - name with space, 1starting_from_number, name!with?symbols.

If you need to get values from inner entities, you need to specify full path to the property: project.id, feature.epic.name.

For example, I want to get user stories with id, name, effort, project (with id, name and process name), feature (with id, name and epic):

/api/v2/UserStory?select={id,name,project:{project.id,project.name,process:project.process.name},feature:{feature.id,feature.name,feature.epic}}

Let's format selector for convenience:

{
   id,
   name,
   project: { 
     project.id,
     project.name,
     process:project.process.name
   },
   feature: {
      feature.id,
      feature.name,
      feature.epic
   }
}

The result is:

   { // fully filled userstory
    "id": 93108,
    "name": "Add Left/Right arrows to scroll widgets library",
    "project": {
      "id": 49105,
      "name": "TP3",
      "process": "Kanban TP"
    },
    "feature": {
      "id": 49126,
      "name": "Dashboards MVF",
      "epic": { // as far as epic was requested as a field, it contains only "id" and "name"
        "id": 90678,
        "name": "Dashboards"
      }
    },
    {
      "id": 93114,
      "name": "Study Projectplace tool",
      "project": {
        "id": 37819,
        "name": "AVM: MKT_Backlog",
        "process": "Sales: General"
      },
      "feature": { // This UserStory has no feature, so result projection will include the empty "feature" object

      }
    }

Selectors for collections

Along with simple fields and related entities, you also can request inner collections. E.g. I want to get projects with: all User Stories.

https://md5.tpondemand.com/api/v2/Project?select={id,name,userStories}

  • userstories - list of all User Stories in format {id,name}. As far it is just a field, it doesn't require explicit name

Selectors: Custom Calculations over nested collections

You can request inner collections with filters, projections, and aggregations. E.g. I want to get projects with:

  • all non-closed bugs
  • sum of feature efforts
  • count of opened requests

More information: Selectors: Custom Calculations over nested collections

Final selectors: Custom Calculations over result output

It is also possible to apply aggregation to whole result collection.

More information: Final selectors: Custom Calculations over result output

.NET Expressions

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

Filtering expressions

Filtering expressions should be valid .NET expressions that return true or false. You use these expressions in where 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

Parameter named orderBy sorts results in ascending or descending order. Ascending is default option.
To specify the order you should place 'asc' or 'desc' after selector.
To enable additional sort criteria to sort a sequence you can enumerate them using comma.

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
    }
]

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