Visual Studio Team Services REST API Reference

Welcome to the Visual Studio Team Services REST API Reference.

Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the service's resources. This article walks you through:

  • The basic components of a REST API request/response pair.
  • Overviews of creating and sending a REST request, and handling the response.

Note

Most REST APIs have a corresponding .NET Client Library that can be used to greatly simplify your client code. Find out more about them at the .NET Client Libraries documentation.

Components of a REST API request/response pair

A REST API request/response pair can be separated into five components:

  1. The request URI, in the following form: VERB https://{instance}[/{collection}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • instance: The Team Services account or TFS server you're sending the request to. They are structured as follows,
      • Team Services: {account}.visualstudio.com
      • TFS: {server:port}/tfs (the default port is 8080)
    • collection: The value for collection should be DefaultCollection for both TFS and Team Services.
    • resource path: The collection should be followed by _apis/{area}/{resource}. For example _apis/wit/workitems.
    • api-version: Every API request should include an api-version to avoid having your app or service break as APIs evolve. api-versions are in the following format: `{major}.{minor}[-{stage}[.{resource-version}]], for example:

      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

      Note: area and team-project are optional, depending on the API request.

  2. HTTP request message header fields:

    • A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Azure REST APIs support GET, HEAD, PUT, POST, and PATCH methods.
    • Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request.
  3. Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters.
    • For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as application/json.
  4. HTTP response message header fields:
    • An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
    • Optional additional header fields, as required to support the request's response, such as a Content-type response header.
  5. Optional HTTP response message body fields:
    • MIME-encoded response objects may be returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the Content-type response header. For example, when you request an access token from Azure AD, it will be returned in the response body as the access_token element, one of several name/value paired objects in a data collection. In this example, a response header of Content-Type: application/json is also included.

Create the request

Authenticate

There are many ways to authenticate your application or service with Team Services or TFS. The following table is an excellent way to decide which method is the best for you:

Type of application Description example Authentication mechanism Code samples
Interactive client-side GUI based client side application Windows app enumerating bugs for a user Active Directory authentication library (ADAL) sample
Interactive Javascript GUI based Javascript application AngularJS single page app displaying work items for a user ADAL sample (coming soon)
Non-interactive client-side Headless text only client side application Console app displaying all bugs assigned to a user Device Profile sample
Interactive web GUI based web application Custom Web dashboard displaying build summaries OAuth sample
TFS application TFS app using the Client OM library TFS extension displaying team bug dashboards Client Libraries sample
VSTS Extension Visual Studio Team Services extension Agile Cards VSS Web Extension SDK sample walkthrough

Note: You can find more information on authentication on our authentication guidance page.

Assemble the request

Team Services

For Team Services, instance is {account}.visualstudio.com and collection is DefaultCollection, so the pattern looks like this:

VERB https://{account}.VisualStudio.com/DefaultCollection/_apis[/{area}]/{resource}?api-version={version}

For example, here's how to get a list of team projects in a Visual Studio Team Services account.

curl -u {username}[:{personalaccesstoken}] https://{account}.VisualStudio.com/DefaultCollection/_apis/projects?api-version=2.0

If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). The resulting string can then be provided as an HTTP header in the format:

Authorization: Basic BASE64PATSTRING

Here it is in C# using the HttpClient class.

public static async void GetProjects()
{
    try
    {
        var personalaccesstoken = "PAT_FROM_WEBSITE";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = await client.GetAsync(
                        "https://{account}.visualstudio.com/DefaultCollection/_apis/projects"))
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

Most samples on this site use Personal Access Tokens as they're a compact example for authenticating with the service. However, there are a variety of authentication mechanisms available for VSTS including ADAL, OAuth and Session Tokens. Refer to the Authentication section for guidance on which one is best suited for your scenario.

TFS

For TFS, instance is {server:port}/tfs and by default the port is 8080. The default collection is DefaultCollection, but can be any collection.

Here's how to get a list of team projects from TFS using the default port and collection.

curl -u {username}[:{personalaccesstoken}] https://{server}:8080/tfs/DefaultCollection/_apis/projects?api-version=2.0

The examples above use personal access tokens, which requires that you create a personal access token.

Process the response

You should get a response like this.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

The response is JSON. That's generally what you'll get back from the REST APIs although there are a few exceptions, like Git blobs.

Now you should be able to look around the specific API areas like work item tracking or Git and get to the resources that you need. Keep reading to learn more about the general patterns that are used in these APIs.