Azure DevOps API Essential Guide

What type of API does Azure DevOps provide?

REST API

• Azure DevOps has a comprehensive REST API that allows developers to interact with and automate various Azure DevOps services.

• The REST API uses standard HTTP methods like GET, POST, PATCH, DELETE etc. for different operations.

• It supports JSON as the data format for requests and responses.

Key Features

• Provides programmatic access to Azure DevOps services like Azure Boards, Repos, Pipelines, Test Plans etc.
• Allows automation of workflows and integration with other tools and services.
• Supports authentication via Personal Access Tokens or OAuth 2.0.
• Has versioning to ensure backward compatibility as new API versions are released.

Other API Types

• While REST is the primary API, Azure DevOps also offers some GraphQL endpoints for certain services like Work Item Tracking.
• There is no SOAP API for Azure DevOps.

Best Practices

• Use API versions to ensure stability of integrations.
• Implement proper error handling and retries for API requests.
• Follow rate limiting guidelines to avoid throttling.
• Use Personal Access Tokens with appropriate scopes for authentication.

In summary, Azure DevOps provides a robust REST API as its primary programmatic interface, with some additional GraphQL capabilities for specific services. This allows developers to build powerful integrations and automate DevOps workflows using Azure DevOps.

Does the Azure DevOps API have webhooks?

Yes, the official Azure DevOps API does support webhooks. Here are the key points about webhooks in Azure DevOps:

Webhook Support

• Azure DevOps provides a service hooks feature that allows you to create webhooks to send notifications to external services when certain events occur in your Azure DevOps project.

• Webhooks can be configured to send a JSON representation of an event to any service with a public HTTP or HTTPS endpoint.

Event Types

You can subscribe to a wide variety of event types in Azure DevOps, including:

• Build and Release events:

  • Build completed
  • Release created/abandoned
  • Release deployment approval completed/pending
  • Release deployment completed/started

• Pipeline events:

  • Run state changed
  • Run stage state changed
  • Run stage waiting for approval
  • Run stage approval completed
  • Job state changed

• Code events:

  • Code checked in
  • Code pushed
  • Pull request created/updated/commented on

• Work item events:

  • Work item created/updated/deleted/restored
  • Work item commented on

Creating Webhooks

• Webhooks can be created through the Azure DevOps web interface or programmatically using the REST API.

• When creating a webhook, you specify:

  • The event type to subscribe to
  • The target service (webhook endpoint)
  • Any additional configuration required for the specific event type

Limitations

• Each webhook subscription is tied to a single event type. You cannot create a single webhook that listens to multiple event types.

• To receive notifications for multiple event types, you need to create separate webhook subscriptions for each event type.

Best Practices

• Use the Azure DevOps REST API to programmatically create and manage webhook subscriptions if you need to set up multiple webhooks.

• Ensure your webhook endpoint can handle the volume of events it may receive, especially for frequently occurring events like code pushes in active repositories.

• Implement proper security measures on your webhook endpoint to validate incoming requests from Azure DevOps.

In summary, Azure DevOps provides robust webhook support with a wide range of event types, allowing you to integrate your Azure DevOps projects with external services and automate workflows based on various events occurring in your development process.

Rate Limits and other limitations

Here are the key points about the API rate limits for Azure DevOps:

Global Consumption Limit

• The global consumption limit is 200 Azure DevOps throughput units (TSTUs) within a sliding 5-minute window [1].

• This limit applies to individual users and pipelines [1].

Rate Limiting Headers

Azure DevOps returns the following headers to help API clients handle rate limiting [1]:

• Retry-After: How long to wait before sending the next request (in seconds)
• X-RateLimit-Resource: The service and threshold type that was reached
• X-RateLimit-Delay: How long the request was delayed (in seconds)
• X-RateLimit-Limit: Total number of TSTUs allowed before delays
• X-RateLimit-Remaining: Number of TSTUs remaining before being delayed
• X-RateLimit-Reset: Time when usage would return to 0 if consumption stopped

Best Practices

• Monitor the X-RateLimit-Remaining and X-RateLimit-Limit headers to track approaching the limit [1].

• Respond to the Retry-After header by waiting before sending another request [1].

• Spread out requests over time to avoid hitting limits [1].

• Use the reporting APIs instead of queries for large data pulls [3].

• Only push actionable work items into Azure DevOps [3].

Other Limits

• 1000 projects per organization (soft limit of 300 before performance degrades) [4]

• Various limits on work items, queries, backlogs, boards etc. [4]

• 10,000 work item revision limit for updates via REST API [4]

The key is to monitor the rate limit headers, throttle requests as needed, and follow best practices to avoid hitting the global 200 TSTU / 5 minute limit. Proper API usage can help prevent rate limiting issues.

Latest API Version

Based on the search results provided, here is the answer to your question about the most recent version of the Azure DevOps API:

The most recent version of the Azure DevOps API is 7.1.

Key points to consider:

1. Azure DevOps Services currently supports API versions from 1.0 to 7.0 [1].

2. The latest version mentioned in the API and TFS version mapping table is 7.1, which is associated with "Azure DevOps Server vNext" [3].

3. API versions are in the format {major}.{minor}[-{stage}[.{resource-version}]]. For example, 1.0, 1.1, 1.2-preview, 2.0 [1].

4. Major API version releases typically align with Team Foundation Server (TFS) RTM releases [1].

5. For Azure DevOps Services (cloud version), you generally don't need to be too concerned about which version you're using, as it supports versions 1.0 to 6.0 [2].

Best practices:

1. Always specify the API version with every request to ensure compatibility [1].

2. When using the API, it's recommended to use the latest stable version available for your Azure DevOps instance.

3. If you're working with a specific Azure DevOps Server version, refer to the version mapping table to determine the appropriate API version [3].

4. Be aware that preview versions of APIs may be deprecated and deactivated after 12 weeks once a stable version is released [1].

5. When building applications that integrate with Azure DevOps, consider using client libraries which can simplify your code and handle versioning for you [3].

It's important to note that while 7.1 is the latest version mentioned, it's associated with "Azure DevOps Server vNext," which suggests it may be a future release. For current production use, version 7.0 might be the most recent stable version for Azure DevOps Services.

How to get a Azure DevOps developer account and API Keys?

To get a developer account for Azure DevOps and create an API integration, you need to follow these steps:

Sign up for Azure DevOps

1. Go to the Azure DevOps website (https://dev.azure.com) and sign up for a free account using your Microsoft account or work/school account.

2. Once signed up, you'll have access to Azure DevOps Services, which includes features like Azure Repos and Azure Pipelines.

Create a Personal Access Token (PAT)

1. In Azure DevOps, go to your user settings and select "Personal access tokens".

2. Create a new PAT with the necessary scopes for your API integration. This token will be used for authentication when making API calls.

Set up your API integration

1. Determine which Azure DevOps REST APIs you need to use for your integration. The APIs follow a common pattern:

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

   For Azure DevOps Services, the pattern is:

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

2. Use your PAT for authentication when making API calls. You can include it in the Authorization header as a Base64 encoded string.

3. Consider using the Azure DevOps .NET Client Libraries if you're working with .NET, as they provide a more convenient way to interact with the APIs.

What can you do with the Azure DevOps API?

Based on the search results provided, I can give you an overview of the data models you can interact with using the Azure DevOps API. Here's a list of bullet points going over what is possible for each data model:

Work Items

• Create new work items programmatically
• Update existing work items
• Query work items based on specific criteria
• Retrieve information about specific work items

Builds

• Trigger new builds programmatically
• Update build definitions
• Retrieve information about builds

Releases

• Create new releases programmatically
• Update release definitions
• Retrieve information about releases

Projects

• Create new projects
• Update project settings
• Retrieve project information

Repositories

• Create and manage repositories
• Retrieve information about code commits
• Manage pull requests

Test Plans

• Create and manage test plans
• Update test cases
• Retrieve test results

Analytics

• Access analytics data through OData API
• Interact with entity sets like WorkItems, Pipelines, and TestResults
• Filter, aggregate, and summarize analytics data

Pipelines

• Create and manage pipeline definitions
• Trigger pipeline runs
• Retrieve pipeline run results

Users and Permissions

• Manage user accounts
• Assign and modify permissions

Service Connections

• Create and manage service connections

General API Interactions

• Use various HTTP methods (GET, PUT, POST, PATCH) to interact with Azure DevOps resources
• Authenticate and authorize API requests using service connections or Personal Access Tokens (PATs)

It's important to note that the available data and operations may vary depending on the API version you're using. The latest supported version is v2.0, with v4.0-preview being the latest preview version. Always refer to the official Azure DevOps API documentation for the most up-to-date and comprehensive information on available data models and operations.