Share via

Get started with the REST APIs

  • Article

TFS 2018

Integrate your app with Azure DevOps using the REST APIs provided in this article.

The APIs follow a common pattern, like the following example.

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Tip

As APIs evolve, we recommend that you include an API version in every request. This practice can help you avoid unexpected changes in the API that could break.

Azure DevOps Services

For Azure DevOps Services, instance is dev.azure.com/{organization} and collection is DefaultCollection, so the pattern looks like the following example.

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

The following example shows how to get a list of projects in an organization.

curl -u {username}:{personalaccesstoken} https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

If you want to provide the personal access token (PAT) 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

The following example shows 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 = client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects").Result)
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

Most of our samples use PATs, as they're a compact example for authenticating with the service. However, there are various authentication mechanisms available for Azure DevOps Services including Microsoft Authentication Library (MSAL), OAuth, and Session Tokens. For more information, see Authentication guidance, to help you determine which one is best suited for your scenario.

Azure DevOps Server

For Azure DevOps Server, instance is {server:port}. The default port for a non-SSL connection is 8080.

The default collection is DefaultCollection, but you can use any collection.

Here's how to get a list of projects from Azure DevOps Server using the default port and collection across SSL:

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

To get the same list across a non-SSL connection:

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

These examples use PATs, which require that you create a PAT.

Responses

You should get a response like this.

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

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

Now, you can 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.

HTTP verbs

Verb Used for...
GET Get a resource or list of resources
POST Create a resource, Get a list of resources using a more advanced query
PUT Create a resource if it doesn't exist or, if it does, update it
PATCH Update a resource
DELETE Delete a resource

Request headers and request content

When you provide request body (usually with the POST, PUT and PATCH verbs), include request headers that describe the body. For example,

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

HTTP method override

Some web proxies might only support the HTTP verbs GET and POST, but not more modern HTTP verbs like PATCH and DELETE. If your calls might pass through one of these proxies, you can send the actual verb using a POST method, with a header to override the method. For example, you might want to update a work item (PATCH _apis/wit/workitems/3), but you might have to go through a proxy that only allows GET or POST. You can pass the proper verb (PATCH in this case) as an HTTP request header parameter and use POST as the actual HTTP method.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Response codes

Response Notes
200 Success, and there's a response body.
201 Success, when creating resources. Some APIs return 200 when successfully creating a resource. Look at the docs for the API you're using to be sure.
204 Success, and there's no response body. For example, you get this response when you delete a resource.
400 The parameters in the URL or in the request body aren't valid.
401 Authentication failed. Often, this response is because of a missing or malformed Authorization header.
403 The authenticated user doesn't have permission to do the operation.
404 The resource doesn't exist, or the authenticated user doesn't have permission to see that it exists.
409 There's a conflict between the request and the state of the data on the server. For example, if you attempt to submit a pull request and there's already a pull request for the commits, the response code is 409.

Cross-origin resource sharing (CORS)

Azure DevOps Services supports CORS, which enables JavaScript code served from a domain other than dev.azure.com/* to make Ajax requests to Azure DevOps Services REST APIs. Each request must provide credentials (PATs and OAuth access tokens are both supported options). Example:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(replace myPatToken with a personal access token)

Versioning

Azure DevOps REST APIs are versioned to ensure applications and services continue to work as APIs evolve.

Guidelines

  • Specify the API version with every request (required).
  • Format API versions as follows: {major}.{minor}-{stage}.{resource-version}. For example, 1.0, 1.1, 1.2-preview, 2.0.
  • Specify a particular revision of the API when it's in preview, by using the following version format: 1.0-preview.1, 1.0-preview.2. Once an API is released (1.0, for example), its preview version (1.0-preview) is deprecated and can be deactivated after 12 weeks.
  • Upgrade to the released version of the API. Once a preview API is deactivated, requests that specify -preview version get rejected.

Usage

Specify the API version in the header of the HTTP request or as a URL query parameter.

HTTP request header:

Accept: application/json;api-version=1.0

Query parameter:

GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0

Supported versions

For information on supported versions, see REST API versioning, Supported versions.