azure-devops-node-api

Install the Azure DevOps client for Node.js using npm:

npm install azure-devops-node-api --save

To interact with Azure DevOps, you must first create a connection using a collection URL and an authentication handler. For Personal Access Tokens (PAT), use getPersonalAccessTokenHandler.

Note on URLs: While most APIs use the organization level URL (e.g., https://dev.azure.com/{yourorgname}), some APIs like ProfileApi require a deployment level URL structured as https://vssps.dev.azure.com/{yourorgname}.

import * as azdev from "azure-devops-node-api";

// your collection url
let orgUrl = "https://dev.azure.com/yourorgname";

let token: string = process.env.AZURE_PERSONAL_ACCESS_TOKEN;

let authHandler = azdev.getPersonalAccessTokenHandler(token); 
let connection = new azdev.WebApi(orgUrl, authHandler);    

To run the included samples, ensure you have Node.js >= 16 and TypeScript (tsc) >= 4 installed.

1. Install dependencies: npm install
2. Set required environment variables:
   • API_URL: Your Azure DevOps organization URL.
   • API_TOKEN: Your Personal Access Token.
   • API_PROJECT: The name of your project.
3. Execute samples:
   • All samples: npm run samples
   • Specific sample: npm run samples -- <sampleName> (e.g., npm run samples -- projectAnalysis)

# Example environment setup and execution
export API_URL=https://dev.azure.com/yourorgname
export API_TOKEN=your_token_here
export API_PROJECT=myProject

npm run samples

API clients support asynchronous operations using async/await. You can import specific interfaces to ensure type safety when working with returned data structures.

import * as bi from "azure-devops-node-api/interfaces/BuildInterfaces";

async function run() {
    let project: string = "myProject";
    // 'build' is an instance of IBuildApi obtained from the connection
    let defs: bi.DefinitionReference[] = await build.getDefinitions(project);

    defs.forEach((defRef: bi.DefinitionReference) => {
        console.log(`${defRef.name} (${defRef.id})`);
    });    
}

run();

Once a WebApi connection is established, you can retrieve specific API clients (e.g., BuildApi, GitApi) using methods on the connection object. These methods are asynchronous and return the requested client instance.

import * as ba from "azure-devops-node-api/BuildApi";

let build: ba.IBuildApi = await connection.getBuildApi();

The library provides access to a wide range of Azure DevOps services through specialized client classes. Common clients include:

• Build
• Git
• Work
• WorkItemTracking
• Release
• Test
• Wiki
• Core
• ...and many others (e.g., Advanced Security, Dashboard, ExtensionManagement, Profile, etc.).

Node.js Support

• v14 and above: Current and maintained. Supports Node 16 and above.
• v13 and below: End of Life. Contains security vulnerabilities; use at your own risk for Node < 16.

API and TFS Mapping

Use the following table to match the azure-devops-node-api version with your TFS/Azure DevOps Server version:

The library is initialized by importing the main entrypoint. This automatically loads the core WebApi module and necessary extensions required for full functionality. To use the library, import the module as shown in the usage examples.

import trm = require('./WebApi');
require('./extensions');