Azure DevOps REST API

Overview

This skill provides guidance for working with Azure DevOps REST APIs using the official OpenAPI specifications from the vsts-rest-api-specs repository. It helps with implementing new API integrations, understanding API capabilities, and referencing the correct request/response formats.

Key API Areas

Azure DevOps REST APIs are organized into the following main areas:

Core Services

• •core - Projects, teams, processes, and organization-level operations
• •git - Repositories, branches, pull requests, commits
• •build - Build definitions, builds, and build resources
• •pipelines - Pipeline definitions and runs
• •release - Release definitions, deployments, and approvals

Work Item & Planning

• •wit (Work Item Tracking) - Work items, queries, and work item types
• •work - Boards, backlogs, sprints, and team configurations
• •testPlan - Test plans, suites, and cases
• •testResults - Test runs and results

Package & Artifact Management

• •artifacts - Artifact feeds and packages
• •artifactsPackageTypes - NuGet, npm, Maven, Python packages

Security & Governance

• •graph - Users, groups, and memberships
• •security - Access control lists and permissions
• •policy - Branch policies and policy configurations
• •audit - Audit logs and events

Extension & Integration

• •extensionManagement - Extensions and marketplace
• •serviceEndpoint - Service connections
• •hooks - Service hooks and subscriptions

API Specification Structure

The vsts-rest-api-specs repository is organized by API area and version:

specification/
  ├── {api-area}/          (e.g., git, build, pipelines)
  │   ├── 7.2/            Latest stable version
  │   │   ├── {area}.json          OpenAPI spec file
  │   │   └── httpExamples/        Example requests/responses
  │   ├── 7.1/
  │   └── ...

Using the Specifications

1. •Identify the API area - Determine which service area (git, build, wit, etc.) contains the functionality needed
2. •Select the version - Use the latest version (7.2) unless targeting a specific Azure DevOps Server version
3. •Review the OpenAPI spec - The main {area}.json file contains all endpoints, schemas, and parameters
4. •Check httpExamples - Real request/response examples for each endpoint

Implementation Patterns

Pattern 1: Exploring New API Capabilities

When exploring what APIs are available for a specific feature:

1. •Clone the vsts-rest-api-specs repository to /tmp/vsts-rest-api-specs
2. •Browse the specification directory for the relevant API area
3. •Review the OpenAPI spec JSON file for available endpoints
4. •Check httpExamples for real-world usage patterns

Example workflow:

cd /tmp
git clone --depth 1 https://github.com/MicrosoftDocs/vsts-rest-api-specs.git
cd vsts-rest-api-specs/specification/git/7.2
# Review git.json for endpoint definitions
# Check httpExamples/ for request/response samples

Pattern 2: Implementing a New API Feature

When adding new API functionality to the MCP server:

1. •Locate the spec: Find the relevant OpenAPI specification
2. •Review the schema: Understand the request parameters and response format
3. •Check examples: Review httpExamples for real request/response data
4. •Create types: Define TypeScript interfaces based on the OpenAPI schema
5. •Implement handler: Create the feature handler following the repository's feature-based architecture
6. •Add tests: Write unit tests with mocked responses based on httpExamples

Pattern 3: Understanding Request/Response Formats

When you need to understand the exact format of API requests or responses:

1. •Navigate to specification/{area}/{version}/httpExamples/
2. •Find the relevant endpoint example (e.g., GET_repositories.json)
3. •Review both the request parameters and response body structure
4. •Use this as the basis for creating Zod schemas and TypeScript types

Reference Resources

scripts/

Contains helper utilities for working with the API specifications:

• •clone_specs.sh - Clone or update the vsts-rest-api-specs repository
• •find_endpoint.py - Search for specific endpoints across all API specs

references/

Contains curated reference documentation:

• •api_areas.md - Comprehensive list of all API areas and their purposes
• •common_patterns.md - Common request/response patterns across APIs
• •authentication.md - API authentication methods and patterns

Usage Tips

Finding the right API:

• •Use the OpenAPI spec's paths section to find endpoint URLs
• •Check the tags property to understand the API category
• •Review the operationId for the internal Azure DevOps method name

Understanding schemas:

• •All data models are in the definitions section of the OpenAPI spec
• •Look for $ref properties to follow schema references
• •Use httpExamples to see actual data structures

Version selection:

• •Use version 7.2 for Azure DevOps Services (cloud)
• •Check azure-devops-server-{version} folders for on-premises versions
• •API versions are additive - newer versions include all older functionality

Integration with This Repository

When implementing features in this MCP server:

1. •Follow the feature-based architecture: Create features in src/features/{api-area}/
2. •Use Zod for validation: Define schemas based on OpenAPI definitions
3. •Reference the specs: Link to the relevant OpenAPI spec in code comments
4. •Include examples: Use httpExamples data for test fixtures
5. •Match naming: Use consistent naming with the Azure DevOps API (e.g., repositoryId, pullRequestId)

Example feature implementation pattern:

// src/features/{api-area}/{operation}/
├── feature.ts          // Core implementation using azure-devops-node-api
├── schema.ts           // Zod schemas based on OpenAPI definitions
├── feature.spec.unit.ts // Tests using httpExamples data
└── index.ts            // Exports