Visual Studio Team Service - Trigger A Build Using Any HTTP Client

In this post, we are going to see how easily we can trigger a new build in VSTS from any of our widely used HTTP clients like fiddler or postman.

Prerequisites

For this, we will require an active VSTS account with administrative privileges.
Prior knowledge of VSTS build definitions.
A simple build definition in a team project.

If you are new to VSTS, please check the official documentation here.

I would like to make this post short and to the point so I will not go into details on how to setup team project, upload your code base, and how to create CI CD pipeline for your projects.

If you want to know more and setup CI CD pipeline for ASP.NET Core services, please visit my previous blogs here.

Now, that we have a total setup with Team project and build definitions, let's move towards consuming the VSTS API’s which are exposed by the Team Service.

REST API over VSTS and TFS

VSTS exposes a whole lot of APIs for different sets of operations, such as -

Account and profile
Projects and teams
Work (Agile)
Build
Version control
Security… etc.

There are many more features that are exposed over REST API for VSTS. To find out all the cool features, please visit their official documentation here.

In this post, we will see how to consume the Build API and trigger or queue a build in a few simple steps using any HTTP REST client that is available on your local machine which, in our case, we will be using Fiddler.

Step 1 Generating the authorization token:

In order to invoke the VSTS APIs, we will need some mode of authentication for our account. The easiest way to do that is to create a PAT (Personal Access Token) from the VSTS portal. Though it is easy and effective for small problems and use cases, for proper business scenarios, please check out the official documentation for guideline by VSTS team here.

For this demo, we will proceed with creating a PAT and how to use it for authenticating our API calls.

In order to generate a PAT, we need to first login to our VSTS account and then from the top right corner in the profile section, we need to go to Security as shown in the picture below.

VSTS
In the Security tab, select Personal access tokens which will display the list of previously created PATs. Now, in order to generate a new token, we need to click on Add and then give our token a description so that it can be identified later, select its expiry date, and select its roles (scopes).

VSTS
Note

We need to copy and save the generated key because VSTS will not store its value in the portal once it's generated. For more details regarding PAT, please visit here.

Step 2 Calling API using Fiddler

Now, that we have our personal access token, let's proceed towards calling the Build API which can queue a new build. We will be using the POST method to call the below URL which will trigger a new build. Let's see the HTTP request in details:

URL - https://{instance}/DefaultCollection/{project}/_apis/build/builds?api-version={version}

HTTP method - POST

Headers

{
Content - type: application / json
authorization: Basic < username: PAT in base64string format >
}
Request body: {
"definition": {
"id": 1
}
}

In the above section, we have a few things to talk about.

First is the URL - Here, {instance} refers to your VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}) and {project} is the Team project ID or name in which the build definition is created.

Secind is the authorization header. In order to compose the token, we can use a tool in Fiddler to generate the base64 string for us. The token for Basic Authorization should be in format: username-Personal Access token

In order to open the tool in Fiddler, go to Tools → TextWizard or press ctrl+E.

VSTS

In the transfer section select Base64 and copy the value that is generated by giving your VSTS username - PAT

Third, in the Request body, we have sent the Definition → Id = 1; This is the build definition Id that we are going to queue. Make sure you select the correct build definition Id while queuing the build.

In order to find the build definition Id from the VSTS portal, go to the "Build & Release" tab in your Team Project. Select and edit the build definition that you would want to queue and click on Variables as below.

VSTS

The system.definitionId is the definition Id for that build definition. So, the final request composed in Fiddler will look something like this.

VSTS

The POST request returns the build information if the request is successful. There are other APIs as well which VSTS exposes, through which we can perform several other activities. To check out the list of APIs exposed as extension points, please see the documentation here.

I hope this post will help you to get started on how to use the VSTS APIs. If you like the post, please recommend it to your friends and colleagues.

Until then, happy coding!