TFS REST API: Get Item Commit History In One Branch

by Sebastian Müller 52 views

Hey guys! Are you trying to retrieve the commit history for a specific item within a particular branch in your Git repository using the Team Foundation Server (TFS) REST API? You've come to the right place! This guide will walk you through the process, ensuring you can effectively leverage the TFS REST API to access the information you need. We'll break down the steps, provide examples, and offer best practices to help you master this task. Whether you're using TFS 2015, Azure DevOps, or a newer version, the core principles remain the same. Let's dive in!

Understanding the TFS REST API

Before we get started, let's ensure we're all on the same page regarding the TFS REST API. The TFS REST API allows developers to interact with Team Foundation Server and Azure DevOps Services programmatically. It provides endpoints for various operations, including working with Git repositories, work items, builds, and releases. For our specific goal—retrieving commits for an item in a branch—we'll be focusing on the Git-related endpoints.

The TFS REST API is a powerful tool that enables you to automate tasks, integrate with other systems, and extract data for reporting and analysis. Understanding how to use it effectively can significantly enhance your development workflow.

The base URL for the TFS REST API typically follows this pattern:

https://{accountName}.visualstudio.com/{projectName}/_apis/git/{resource}?api-version={version}
  • {accountName}: Your Azure DevOps organization name.
  • {projectName}: The name of your project.
  • {resource}: The specific Git resource you want to access (e.g., repositories, commits).
  • {version}: The API version you're using (e.g., 7.1).

For retrieving commits, we'll primarily use the /commits endpoint. This endpoint allows us to fetch commit history, filter by various criteria, and retrieve detailed information about each commit.

Identifying the Necessary Parameters

To successfully retrieve the commit history for a specific item in a branch, we need to identify the parameters required by the TFS REST API. The key parameters we'll be working with include:

  1. Repository ID: This is the unique identifier for your Git repository within TFS. You can find this ID in the repository settings or by using the GET /repositories endpoint.
  2. Branch Name: The name of the branch you're interested in (e.g., main, develop, feature/my-feature).
  3. Item Path: The path to the specific item (file or folder) within the repository for which you want to retrieve the commit history. For instance, src/MyFile.cs.
  4. API Version: The version of the TFS REST API you're using. It's a good practice to use the latest version to leverage the newest features and improvements.

To construct the API request, we'll need to encode these parameters correctly. The basic structure of the request URL will look something like this:

https://{accountName}.visualstudio.com/{projectName}/_apis/git/repositories/{repositoryId}/commits?searchCriteria.itemVersion.version={branchName}&searchCriteria.itemPath={itemPath}&api-version={version}

Let's break down the important parts of this URL:

  • /repositories/{repositoryId}/commits: Specifies that we're querying commits for a specific repository.
  • searchCriteria.itemVersion.version={branchName}: Filters the commits to those within the specified branch.
  • searchCriteria.itemPath={itemPath}: Filters the commits to those that affect the specified item path.
  • api-version={version}: Specifies the API version.

Constructing the API Request

Now that we understand the parameters, let's walk through constructing the API request step by step. Imagine we want to get the commit history for the file src/MyFile.cs in the main branch of a repository with the ID 12345678-1234-1234-1234-123456789012 in an Azure DevOps project named MyProject within the organization MyOrg.

Here's how we'd construct the API request URL:

  1. Base URL: https://MyOrg.visualstudio.com/MyProject/_apis/git
  2. Resource: /repositories/12345678-1234-1234-1234-123456789012/commits
  3. Query Parameters:
    • searchCriteria.itemVersion.version=main
    • searchCriteria.itemPath=src/MyFile.cs
    • api-version=7.1

Putting it all together, the complete URL would be:

https://MyOrg.visualstudio.com/MyProject/_apis/git/repositories/12345678-1234-1234-1234-123456789012/commits?searchCriteria.itemVersion.version=main&searchCriteria.itemPath=src/MyFile.cs&api-version=7.1

This URL is what you'll use to make the API call. You can use tools like curl, Postman, or programming languages like C# or Python to send the request.

Making the API Call

With the URL constructed, the next step is to make the API call. The method you use will depend on your preferred tool or programming language. Let's look at examples using curl and C#.

Using curl

curl is a command-line tool widely used for making HTTP requests. To make the API call using curl, you'll need to include an authentication token. Azure DevOps uses Personal Access Tokens (PATs) for authentication. Here’s how to use curl:

  1. Generate a PAT: In Azure DevOps, navigate to User Settings > Personal Access Tokens and create a new token with the necessary permissions (e.g., vso.code_read).

  2. Execute the curl command:

    curl -u :{PAT}