Get Мaximum from TeamCity Integration through REST API

Connect your Bitbucket to the TeamCity CI/CD server with TeamCity Integration for Bitbucket to run builds right from Bitbucket in one click, view build results, logs and artifacts right next to your code, and never lose time switching.

Working in a team is a great challenge when you need close collaboration between different people of different occupations and specializations. This becomes a real pain when members of a team do not have direct communication or communication is complicated with external factors. Here come special collaboration platforms that leverage the gap between people and create a single environment for peer-to-peer interaction and efficient knowledge or information sharing.

Today we will try to review an environment of TeamCity, JIRA and Confluence integrated into a single ecosystem for quick and easy data retrieval about builds and agents from TeamCity.

So what capabilities does this integration offer to the team of software developers? First of all, Confluence can be used as a collaboration platform listing the latest builds within the appropriate project and configuration. Project Managers and Team Leads can be always aware of the progress on the project and track the current activity on project development. JIRA can be used by developers and quality assurance engineers. Developers can track progress on issues and tasks, and quality assurance engineers can track the completion of development and proceed to testing of functionality.

TeamCity is already bundled with JIRA integration capabilities, but Atlassian JIRA does not have a native tool that can fetch build data and show it in JIRA issues, the same is true and for Confluence. The solution from StiltSoft team allows you to establish full-fledged integration between TeamCity, JIRA and Confluence, in addition to standard integration from JetBrains team available in Teamcity.

In our blog post we will show how you can create tools for fetching data from TeamCity via Rest API and showing this build data in some application.

Connecting to TeamCity Server

TeamCity provides REST API, which powerful capabilities can be used for fetching various data from TeamCity server. You need to send a HTTP request to REST API to fetch the required piece of TeamCity data. In order to get the requested piece of data you need to authorize on the server through one of the following ways:

1. Basic HTTP Authentication – you need to provide the appropriate TeamCity username and password with the request. In this case, you need to include ‘httpAuth’ into your GET request: http://teamcity-server/httpAuth/app/rest/builds.
2. Guest Authentication – you needn’t provide the valid username and password, just include ‘guestAuth’ into your GET request: http://teamcity-server/guestAuth/app/rest/builds.

Once your request has been processed, TeamCity server will return a piece of XML data, which you can further parse and output into your application.

Fetch Useful Build Data

First of all, TeamCity server stores a lot of build data, which is the point of interest #1 for you. Build data contains a lot of useful information about builds, their status, time for execution, completion status of tests and related issues in the issue tracking system. The best way is to fetch builds in batches – 20 or 50 builds per batch. You can use the following request to REST API of TeamCity server:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k https://teamcity-server/httpAuth/app/rest/builds?locator=canceled:any,count:20,start:20,branch:(default:any)

You get a XML response with 20 builds, as follows:

<builds count="20" href="/httpAuth/app/rest/builds?locator=canceled:any,count:20,start:20,branch:(default:any)" nextHref="/httpAuth/app/rest/builds?locator=canceled:any,count:20,start:40,branch:(default:any)" prevHref="/httpAuth/app/rest/builds?locator=canceled:any,count:20,start:0,branch:(default:any)">
 <!--The piece of code is omitted -->
 <build id="6863" buildTypeId="SmartAttachments_Master" number="87" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6863" webUrl="http://teamcity.stiltsoft.com/viewLog.html?buildId=6863&buildTypeId=SmartAttachments_Master"/>
 <build id="6862" buildTypeId="SmartAttachments_Master" number="86" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6862" webUrl="http://teamcity-server/viewLog.html?buildId=6862&buildTypeId=SmartAttachments_Master"/>
 <build id="6861" buildTypeId="SmartAttachments_Master" number="85" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6861" webUrl="http://teamcity-server/viewLog.html?buildId=6861&buildTypeId=SmartAttachments_Master"/>
 <build id="6860" buildTypeId="SmartAttachments_Master" number="84" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6860" webUrl="http://teamcity-server/viewLog.html?buildId=6860&buildTypeId=SmartAttachments_Master"/>
 <build id="6859" buildTypeId="SmartAttachments_Master" number="83" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6859" webUrl="http://teamcity-server/viewLog.html?buildId=6859&buildTypeId=SmartAttachments_Master"/>
 <!--The piece of code is omitted -->
 <build id="6856" buildTypeId="SmartAttachments_Master" number="82" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6856" webUrl="http://teamcity-server/viewLog.html?buildId=6856&buildTypeId=SmartAttachments_Master"/>
 <build id="6855" buildTypeId="SmartAttachments_Master" number="81" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6855" webUrl="http://teamcity-server/viewLog.html?buildId=6855&buildTypeId=SmartAttachments_Master"/>
 <build id="6854" buildTypeId="SmartAttachments_Master" number="80" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6854" webUrl="http://teamcity-server/viewLog.html?buildId=6854&buildTypeId=SmartAttachments_Master"/>
</builds>

You can further parse this build data and use it for output to the interface of your application.

Additionally, you can get detailed information about each build from the batch by making the following request:

<code class="java plain" style="color: #000000 !important;">curl -D- -u guest:guest -X GET -H </code><code class="java string" style="color: #003366 !important;">"Content-Type: text/xml"</code> <code class="java plain" style="color: #000000 !important;">-k https:</code><code class="java comments" style="color: #008200 !important;">//teamcity-server/httpAuth/app/rest/builds/id:378626</code>

The XML response you get will be the following:

<build id="6854" buildTypeId="SmartAttachments_Master" number="80" status="SUCCESS" state="finished" branchName="master" defaultBranch="true" href="/httpAuth/app/rest/builds/id:6854" webUrl="http://teamcity-server/viewLog.html?buildId=6854&buildTypeId=SmartAttachments_Master">
 <statusText>Success</statusText>
 <buildType id="SmartAttachments_Master" name="Master" projectName="Smart Attachments" projectId="SmartAttachments" href="/httpAuth/app/rest/buildTypes/id:SmartAttachments_Master" webUrl="http://teamcity-server/viewType.html?buildTypeId=SmartAttachments_Master"/>
 <queuedDate>20141128T133710+0300</queuedDate>
 <startDate>20141128T133710+0300</startDate>
 <finishDate>20141128T133725+0300</finishDate>
 <triggered type="vcs" details="jetbrains.git" date="20141128T133710+0300"/>
 <lastChanges count="1">
 <change id="4927" version="f6b67f30820c02182b24ca9d596d24a0fb74b602" username="akhaneev" date="20141128T132640+0300" href="/httpAuth/app/rest/changes/id:4927" webUrl="http://teamcity-server/viewModification.html?modId=4927&personal=false"/>
 </lastChanges>
 <changes href="/httpAuth/app/rest/changes?locator=build:(id:6854)"/>
 <revisions count="1">
 <revision version="f6b67f30820c02182b24ca9d596d24a0fb74b602">
 <vcs-root-instance id="541" vcs-root-id="SmartAttachments_HttpsStashStiltsoftComScmAcaAttachmentCategoryAddOnGit" name="https://stash-server/scm/aca/attachment-category-add-on.git" href="/httpAuth/app/rest/vcs-root-instances/id:541"/>
 </revision>
 </revisions>
 <agent href="/httpAuth/app/rest/agents/id:2" id="2" name="tm7" typeId="2"/>
 <artifacts href="/httpAuth/app/rest/builds/id:6854/artifacts/children"/>
 <relatedIssues href="/httpAuth/app/rest/builds/id:6854/relatedIssues"/>
 <statistics href="/httpAuth/app/rest/builds/id:6854/statistics"/>
</build>

If you want to find out the related issues, you can perform an additional request which fetches information about the related issues in the issue tracker (for example, YouTrack or JIRA):

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k https://teamcity-server/httpAuth/app/rest/builds/id:378549/relatedIssues

You will receive the following XML response from TeamCity server:

<issuesUsages count="1" href="/httpAuth/app/rest/builds/id:6854/relatedIssues">
 <issueUsage>
 <changes count="1">
 <change id="4927" version="f6b67f30820c02182b24ca9d596d24a0fb74b602" username="akhaneev" date="20141128T132640+0300" href="/httpAuth/app/rest/changes/id:4927" webUrl="http://teamcity-server/viewModification.html?modId=4927&personal=false"/>
 </changes>
 <issue id="SMART-40" url="https://jira-server/browse/SMART-40"/>
 </issueUsage>
</issuesUsages>

You can use the received project key and issue number for mapping to the particular issue in the issue tracking system.

Quality assurance engineers can easily monitor the status of each issue and can instantly proceed to functionality testing once the corresponding build with the fix is complete. So they needn’t wait for the development team when someone will resolve this issue in the issue tracking system.

Find Out Available TeamCity Agents

You can also retrieve information about build agents and get the list of the currently active agents. This can be useful for the quality assurance engineer and developers to track availability of the specific build agent at the definite period of time. You can make the following request to display the list of available build agents:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k  https://teamcity-server/httpAuth/app/rest/agents

You will get the following XML data about build agents:

<agents count="2" href="/httpAuth/app/rest/agents">
 <agent href="/httpAuth/app/rest/agents/id:4" id="4" name="teamcity2k8" typeId="4"/>
 <agent href="/httpAuth/app/rest/agents/id:2" id="2" name="tm7" typeId="2"/>
</agents>

If needed, you can get detailed information about a specific agent, you should use the following request with the ID of the required agent:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k  https://teamcity-server/httpAuth/app/rest/agents/id:4

You will receive the following XML data about the agent with the list of its requirements for running builds:

<agent href="/httpAuth/app/rest/agents/id:4" id="4" name="teamcity2k8" typeId="4" connected="true" enabled="true" authorized="true" uptodate="true" ip="192.168.0.31">
 <properties count="145">
 <property name="DotNetFramework2.0.50727_x64_Path" value="C:\Windows\Microsoft.NET\Framework64\v2.0.50727"/>
 <property name="DotNetFramework2.0.50727_x86_Path" value="C:\Windows\Microsoft.NET\Framework\v2.0.50727"/>
 <property name="DotNetFramework2.0_x64" value="2.0.50727"/>
 <!-- The piece of code is omitted -->
 <property name="DotNetFramework2.0_x86_Path" value="C:\Windows\Microsoft.NET\Framework\v2.0.50727"/>
 <property name="teamcity.tool.maven3" value="C:\BuildAgent\tools\maven3"/>
 <property name="teamcity.tool.maven3_1" value="C:\BuildAgent\tools\maven3_1"/>
 <property name="teamcity.tool.maven3_2" value="C:\BuildAgent\tools\maven3_2"/>
 </properties>
 <pool id="0" name="Default" href="/httpAuth/app/rest/agentPools/id:0"/>
</agent>

Developers can easily view which build agents are currently in use by other projects and start building the project with another agent. The list of agents can be shown as a gadget on JIRA dashboard or placed as a macro on some Confluence page.

Optionally, you can also get information about the agent pools. Agent pool is a separate group of build agents that are assigned to the specific project for running builds. Any project can be assigned to multiple agent pools. Each build agent can be only assigned to one agent pool. You can run project builds only on build agents from pools assigned to the project. By default, all newly authorized agents are included into the Default pool. Agent pools allow you to bind specific agents to specific projects.

Just perform the following request:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k https://teamcity-server/httpAuth/app/rest/agentPools/id:0

In the outputted listing you will get the following XML data:

<agentPool id="0" name="Default" href="/httpAuth/app/rest/agentPools/id:0">
 <projects count="15">
 <project id="TableFilter" name="TableFilter" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:TableFilter" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=TableFilter"/>
 <project id="_Root" name="<Root project>" description="Contains all other projects" href="/httpAuth/app/rest/projects/id:_Root" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=_Root"/>
 <project id="InPlaceEditorforConfluence" name="InPlace Editor for Confluence" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:InPlaceEditorforConfluence" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=InPlaceEditorforConfluence"/>
 <!-- The piece of code is omitted -->
 <project id="ConfluenceTalkPlugin" name="Confluence Talk Plugin" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:ConfluenceTalkPlugin" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=ConfluenceTalkPlugin"/>
 <project id="SmartAttachments" name="Smart Attachments" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:SmartAttachments" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=SmartAttachments"/>
 <project id="NoEmailStorm" name="No Email Storm" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:NoEmailStorm" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=NoEmailStorm"/>
 </projects>
 <agents count="2">
 <agent href="/httpAuth/app/rest/agents/id:4" id="4" name="teamcity2k8" typeId="4"/>
 <agent href="/httpAuth/app/rest/agents/id:2" id="2" name="tm7" typeId="2"/>
 </agents>
</agentPool>

The listing shows the following information:

• projects that can be built by the agents from the pool
• list of agents within the pool

Discover Your Projects in TeamCity

TeamCity API allows you to retrieve information about projects by performing the following request to the server:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k https://teamcity-server/httpAuth/app/rest/projects/

The response will include the list of projects available in TeamCity, as follows:

<projects count="15" href="/httpAuth/app/rest/projects">
 <project id="AWEGRAPHS" name="Awesome Graphs for Stash" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:AWEGRAPHS" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=AWEGRAPHS"/>
 <!-- The piece of code is omitted -->
 <project id="SmartAttachments" name="Smart Attachments" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:SmartAttachments" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=SmartAttachments"/>
 <project id="TeamCityIntegrationLibrary" name="TeamCity Connector" parentProjectId="JiraTeamCityIntegration" href="/httpAuth/app/rest/projects/id:TeamCityIntegrationLibrary" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=TeamCityIntegrationLibrary"/>
 <project id="ConfluenceTeamCityIntegration" name="TeamCity Integration for Confluence" parentProjectId="JiraTeamCityIntegration" href="/httpAuth/app/rest/projects/id:ConfluenceTeamCityIntegration" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=ConfluenceTeamCityIntegration"/>
 <project id="JiraTeamCityIntegration_TeamCityIntegrationForJira" name="TeamCity Integration for JIRA" parentProjectId="JiraTeamCityIntegration" href="/httpAuth/app/rest/projects/id:JiraTeamCityIntegration_TeamCityIntegrationForJira"webUrl="http://teamcity.stiltsoft.com/project.html?projectId=JiraTeamCityIntegration_TeamCityIntegrationForJira"/>
 <project id="BambooVMwarePlugin" name="Virtual Agents for Bamboo" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:BambooVMwarePlugin" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=BambooVMwarePlugin"/>
</projects>

Additionally, you can also fetch data about the project by entering the corresponding project name into the request:

curl -D- -u guest:guest -X GET -H "Content-Type: text/xml" -k https://teamcity-server/httpAuth/app/rest/projects/id:Project_name

<project id="SmartAttachments" name="Smart Attachments" parentProjectId="_Root" href="/httpAuth/app/rest/projects/id:SmartAttachments" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=SmartAttachments">
 <parentProject id="_Root" name="<Root project>" description="Contains all other projects" href="/httpAuth/app/rest/projects/id:_Root" webUrl="http://teamcity.stiltsoft.com/project.html?projectId=_Root"/>
 <buildTypes count="2">
 <buildType id="SmartAttachments_Master" name="Master" projectName="Smart Attachments" projectId="SmartAttachments" href="/httpAuth/app/rest/buildTypes/id:SmartAttachments_Master" webUrl="http://teamcity.stiltsoft.com/viewType.html?buildTypeId=SmartAttachments_Master"/>
 <buildType id="SmartAttachments_MasterIt" name="Master IT" projectName="Smart Attachments" projectId="SmartAttachments" href="/httpAuth/app/rest/buildTypes/id:SmartAttachments_MasterIt" webUrl="http://teamcity.stiltsoft.com/viewType.html?buildTypeId=SmartAttachments_MasterIt"/>
 </buildTypes>
 <templates count="0"/>
 <parameters count="0" href="/app/rest/projects/id:SmartAttachments/parameters"/>
 <vcsRoots count="1" href="/httpAuth/app/rest/vcs-roots?locator=project:(id:SmartAttachments)"/>
 <projects count="0"/>
</project>