Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The TeamCity REST API can be used for integrating applications with TeamCity and for those who want to script interactions with the TeamCity server. TeamCity's REST API allows accessing resources (entities) via URL paths.

Warninginfo

The URL examples on this page assume that your TeamCity server web UI is accessible via the http://teamcity:8111/ URL.

 

 

General Usage Principles

This documentation is not meant to be comprehensive, but just provide some initial knowledge useful for using the API.

...

The general structure of the URL in the TeamCity API is teamcityserver:port/<authType>/app/rest/<entity><apiVersion>/<restApiPath>?<parameters>, where

  • teamcityserver and port define the server name and the port used by TeamCity. This page uses "http://teamcity:8111/" as example URL
  • <authType> (optional) is the authentication type to be used, this is generic TeamCity functionality
  • app means that the request will be directed to the TeamCity application
  • rest means REST API
  • <entity> identifies the required entity. Requests that respond with lists /rest is the root path of TeamCity REST API
  • <apiVersion> (optional) is a reference to specific version of REST API
  • <restApiPath>?<parameters> is the REST API part of the URL

When <restApiPath> represents a collection of items .../app/rest/<itmes> (e.g. .../

...

app/rest/builds

...

), then the URL regularly accepts "locator" parameter which can filter the items returned. Individual items can regularly be addressed by URL in the form .../app/rest/<itmes>/<item_locators>. Both multiple and single items requests regularly support fields parameter.

Locator

In a number of places, you can specify a filter string which defines what entities to filter/affect in the request. This string representation is referred to as "locator" in the scope of REST API.

...

If that does not work, enable debug logging and investigate the log.

API Client Recommendations

When developing a client using REST API it is advised to follow the following recommendations:

  • Make root REST API configurable (e.g. make the "app/rest/<version>" part of the URL configurable)
  • Ignore (do not error out) item's attributes and sub-items which are unknown to the client
  • Set large (and make them configurable) request timeouts. Some API calls can take minutes, especially on a large server.
  • Use HTTP sessions to make consecutive requests (use TCSESSIONID cookie returned from the first authenticated response instead of supplying raw credentials all the time)
  • Beware of partial answers when requesting list of items: some requests are paged by default: if necessary, read and process "nextHref" attribute of the response entity for items collections. Related locator dimensions are "count" and "lookupLimit". 
  • Do not abuse ability to execute automated requests for TeamCity API: do not query API too frequently and restrict the data requested to only that necessary (using due locators and specifying necessary fields). Check the server behavior under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.

 

TeamCity Data Entities Requests

Projects and Build Configuration/Templates Lists

...