A typed client for every Azure DevOps REST API operation. It runs in browsers, Node.js, and
any runtime with fetch, and it validates every response with Zod.
npm install @hypothesi/azure-devops-api zodimport { build, createClient, git } from '@hypothesi/azure-devops-api/services';
const ado = createClient({
organization: 'acme',
auth: { type: 'pat', token: process.env.AZURE_DEVOPS_PAT ?? '' },
});
// Run a WIQL query and get the matching work items.
const wiql = [
'SELECT [System.Id] FROM workitems',
"WHERE [System.WorkItemType] = 'Bug'",
'AND [System.AssignedTo] = @Me',
].join(' ');
const myBugs = await ado.workItems.queryWorkItems(wiql, { project: 'Web' });
// File a bug with Markdown repro steps.
const bug = await ado.workItems.create({
project: 'Web',
type: 'Bug',
fields: {
'System.Title': 'Login button does nothing on iOS',
'Microsoft.VSTS.TCM.ReproSteps': '1. Open the app\n2. Tap **Log in**',
},
markdownFields: ['Microsoft.VSTS.TCM.ReproSteps'],
});
// List the open pull requests that target main.
const { data: pullRequests } = await git.pullRequestsGetPullRequests({
client: ado,
path: { project: 'Web', repositoryId: 'web-app' },
query: {
'searchCriteria.status': 'active',
'searchCriteria.targetRefName': 'refs/heads/main',
},
});
// Find the builds that failed on main.
const { data: failedBuilds } = await build.buildsList({
client: ado,
path: { project: 'Web' },
query: { branchName: 'refs/heads/main', resultFilter: 'failed' },
});Each REST API area, such as wit, git, build, work, and pipelines, is a namespace
with one function per operation. The parameters, request bodies, and responses are typed
from Microsoft's specs.
- A response that does not match its schema throws
ResponseValidationError, so bad data does not reach your code. - Each failure has its own error class, such as
NotFoundError,RateLimitError, andTimeoutError. - Requests have a timeout, accept an
AbortSignal, and retry with exponential backoff. The client does not retry a request that is not safe to repeat, such as creating a work item.
The client README has more examples, and the details of authentication, helpers, errors, and retries. The API reference, with a switcher between API versions, is at https://hypothesi.github.io/azure-devops-api/.
| Package | Contents |
|---|---|
@hypothesi/azure-devops-api |
The client: one entry point per API version, every operation generated from the specs, Zod-validated responses, timeouts, and retries |
@hypothesi/azure-devops-openapi |
The Azure DevOps REST specs as OpenAPI 3.2, with a manifest of API versions, products, and the changes between versions |
Import the entry point for the product your code calls. Every Azure DevOps product accepts all API versions up to its highest one, so a lower entry point works with more products.
| Import | API version | Works with |
|---|---|---|
@hypothesi/azure-devops-api/services |
7.1 | Azure DevOps Services, Azure DevOps Server |
@hypothesi/azure-devops-api/server |
7.1 | Azure DevOps Services, Azure DevOps Server |
@hypothesi/azure-devops-api/server-2022 |
7.0 | Azure DevOps Services, Azure DevOps Server, Azure DevOps Server 2022 |
@hypothesi/azure-devops-api/7.1 |
7.1 | same as /services |
@hypothesi/azure-devops-api/7.0 |
7.0 | same as /server-2022 |
An entry point exports only the operations that exist in its API version. Calling a 7.1-only
operation from /7.0 is a type error.
The client's version is separate from the Azure DevOps API versions:
| Change | Release type |
|---|---|
| New API version entry point, such as 7.2 | Minor |
| Spec update with only identical or additive changes | Minor |
| Spec update with a breaking change in a supported version | Major |
| API version removed because its last product left mainstream support | Major |
| Transport or helper fix | Patch |
The /compatibility export and the azureDevOps field in the client's package.json list the
supported API versions and products. The product rows come from Microsoft's documentation.
See DEVELOPMENT.md for setup, checks, and tests.
MIT. The OpenAPI files are converted from Microsoft's REST API specs, which are under the MIT license.