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:

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

For anyone who is new to VSTS please check their 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 lets 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 API’s 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 few simple steps using any HTTP REST client that is available in your local machine which in our case we will be using Fiddler.

Step 1: Generating the authorization token:

In order to invoke the VSTS API’S 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.

In the Security tab we need to then select Personal access tokens which will display the list of previously created PAT’s. 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 , its expiry date and select its roles(scopes).

PAT
Note: We need to copy and save the generated key because VSTS will not store its value in the portal once its generated. 

For more details regarding PAT please visit here.

Step 2: Calling API using fiddler

Now that we have our personal access token lets proceed towards calling the build API which can queue a new build.

We will using the POST method to call the below URL which will trigger a new build. Lets 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 few things to talk about.

1st 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.

2nd 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 Goto Tools → TextWizard or press ctrl+E

base64

In the transfor section select Base64 and copy the value that is generated by giving your vsts username:PAT

3rd 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.

The system.definitionId is the definition Id for that build definition.

So the final request composed in fiddler will look something like this:

fiddler

The POST request returns the build information if the request is successful. There are other API’s as well which VSTS exposes, through which we can perform several other activities. To check out the list of API’s that is 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 api’s. If you like the post please recommend it to your friends and colleagues.

Till then happy coding :)

Show your support

Clapping shows how much you appreciated Somak Das’s story.