Child pages
  • REST API Plugin

Versions Compared

Key

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

The plugin is bundled since TeamCity 5.0. See the usage details in the current documentation version.

On this page:

Table of Contents

General Info

Vendor

JetBrains

License

Apache 2.0

Type

free, open-source

Plugin Description

Exposes the TeamCity API via REST.

Info

The plugin is bundled since TeamCity 5.0

Usage

If your server is accessible via http://teamcity:8111/ URL, use:
http://teamcity:8111/httpAuth/app/rest/application.wadl - to the get list of supported requests and names of parameters. Provide valid TeamCity username and password with the request as BASIC HTTP authentication.

...

Usage

Details of the API usage are described at the version-specific pages:

REST API Versions

As REST API evolves from one TeamCity version to another, there can be incompatible changes in the protocol.
Under the http://teamcity:8111/httpAuth/app/rest/changes?buildType=id:bt133&sinceChange=id:24234 - (example ids are used) to get all the changes in build configuration since the change identified by id.
URL the latest version is available.
Under http://teamcity:8111/httpAuth/app/rest/users - to get TeamCity users list

As a rule, single value responses are "text/plain" and complex value responses support both "application/xml" and "application/json". Supply appropriate "Accept" header in the request to get necessary response type.

If you get error in response to your request and want to investigate the reason, enable debug logging in the server logs for "jetbrains.buildServer.server.rest" category and then see logs/teamcity-rest.log file.

Feel free to ask questions and provide feedback in our plugins forum.

Build Locator

In a number of places, a string might be specified that defines what builds to filter/affect (referred to as "<buildLocator>"). This is called "build locator" in the scope of REST API.
Examples of supported locators:

  • id:<internal build id> - use it when you need to specify a specific build
  • number:<build number> - to find build by build number, provided build configuration is already specified
  • <dimension1>:<value1>,<dimension2>:<value2> - to find builds by multiple criteria

The list of supported build dimensions:
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration
tags:<tags> - ","(comma) -delimited list of build tags (only builds containing all the specified tags are returned)
status:<SUCCESS/FAILURE/ERROR> - list the builds with the specified status only
user:(<userLocator>) - limit the builds to only those triggered by user specified
personal:<true/false/any> - limit the builds by personal flag.
canceled:<true/false/any> - limit the builds by canceled flag.
running:<true/false/any> - limit the builds by running flag.
pinned:<true/false/any> - limit the builds by pinned flag.
agentName:<name> - agent name to return only builds ran on the agent with name specified
sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified
sinceDate:<date> - limit the list of builds only to those started after the date specified. The date should in the same format as dates returned by REST API.

count:<number> - serve only the specified number of builds
start:<number> - list the builds fromt he list starting from the position specified (zero-based)

If the value is to contain "," symbol, it should be enclosed into parentheses: "(<value>)".

Build Tags

Get tags: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/
Replace tags: PUT http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ (should put the same XML of JSON as returned by GET)
Add tags: POST http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ (should post the same XML of JSON as returned by GET or just a plain-text tag name)
(<buildLocator> here should match a single build only)

Build Pinning

Get current pin status: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/pin/ (returns "true" or "false" text)
Pin: PUT http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
Unpin: DELETE http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
(<buildLocator> here should match a single build only)

Build Statistics

Get build statistics value: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/statistics/
(<buildLocator> here should match a single build only)

Projects and Build Configuration Lists

List of projects: GET http://teamcity:8111/httpAuth/app/rest/projects
Project details: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
<projectLocator> can be id:<internal_project_id> or name:<project%20name>

List of Build Configurations: GET http://teamcity:8111/httpAuth/app/rest/buildTypes
List of Build Configurations of a project: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/buildTypes
Build Configuration details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>
<buildTypeLocator> can be id:<btXXX_internal_buildConfiguration_id> or name:<Build%20Configuration%20name>

Superuser access

If you add "rest.use.authToken=true" internal property, any user can perform superuser operation if authToken is passed in URL parameter. The authToken will be logged into logs/teamcity-rest.log log. You will still need to supply valid user credentials to use this approach.

Data Backup

Start backup: POST http://teamcity:8111/httpAuth/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName=<fileName> where <fileName> in the prefix of the file to save backup to
Get current backup status (idle/running): GET http://teamcity:8111/httpAuth/app/rest/server/backup

<version> URL, other versions CAN be available. Our general policy is to supply TeamCity with ONE previous version.
In TeamCity 7.x you can use "6.0" instead of <version> to get the previous version of the protocol.
In TeamCity 8.0 you can use "6.0" or "7.0" instead of <version> to get earlier versions of the protocol.

API Changes

Breaking changes in the API are described in Upgrade Notes sections of the corresponding TeamCity version documentation.
Please note that additions to the objects returned (such as new XML attributes or elements) are not considered major changes and do not cause the protocol version to increment.
Also, the endpoints marked with "Experiments" comment in application.wadl may change without special notice in future versions.

Logging

You can get details on errors and REST request processing in logs\teamcity-rest.log server log.
Please turn on debug logging (e.g. set Logging Preset to "debug-rest" on Administration/Diagnostics page or modify Log4J "jetbrains.buildServer.server.rest" category) to get details about each processed request.

Sources

If you need to extend the plugin with your functionality, you can base your plugin on the current REST API plugin code, but ensure make sure that your plugin does not interfere with the bundled REST plugin. To achieve this, change the teamcity-plugin.xml file to have a different plugin name and a different value for the "api.path" parameter. Once this is done, your patched plugin and the original REST api plugin can work in the single TeamCity installation.

hidden-data

[Builds|http://buildserver.labs.intellij.net/viewType.html?buildTypeId=bt638] at buildserver.

TeamCity Versions Compatibility

TeamCity 5.0 and above.

...

The plugin is branched with each TeamCity release. The corresponding plugin branch should be used.

Feedback

Feel free to ask questions and provide feedback in our plugins forum.