azure_devops_rust_api 0.37.0

# Azure DevOps Rust API

[![Crates.io](https://img.shields.io/crates/v/azure_devops_rust_api.svg)](https://crates.io/crates/azure_devops_rust_api)
[![docs.rs](https://docs.rs/azure_devops_rust_api/badge.svg)](https://docs.rs/azure_devops_rust_api)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

`azure_devops_rust_api` implements a Rust interface to the Azure DevOps REST API (version 7.1).

The crate is autogenerated from the [Azure DevOps OpenAPI spec](https://github.com/MicrosoftDocs/vsts-rest-api-specs).

## Getting started

1. Add the crate to your `Cargo.toml`, enabling the [feature(s)](#available-features) you need:

```toml
[dependencies]
azure_devops_rust_api = { version = "0.37.0", features = ["git", "pipelines"] }
```

2. Set environment variables:

```sh
export ADO_ORGANIZATION=<organization-name>
export ADO_PROJECT=<project-name>
```

3. Authenticate — see the [Authentication](#authentication) section below.

4. Create a client and call the API — see the [Usage](#usage) section and [examples](examples/).

## Authentication

Two authentication methods are supported:

### Azure CLI (recommended for development)

Run `az login` once, then:

```rust
use azure_devops_rust_api::Credential;
use azure_identity::AzureCliCredential;

let cli_credential = AzureCliCredential::new(None)?;
let credential = Credential::from_token_credential(cli_credential);
```

### Personal Access Token (PAT)

Create a [PAT](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate)
with the minimum required scopes and a short expiry, then:

```rust
use azure_devops_rust_api::Credential;

let token = std::env::var("ADO_TOKEN").expect("Must define ADO_TOKEN");
let credential = Credential::from_pat(token);
```

> **Note:** Treat PATs like passwords — grant only the minimum required scopes and set a short expiry.

## Usage

All modules follow the same pattern:

1. Obtain a `Credential` (see [Authentication](#authentication) above).
2. Create a top-level client via `<module>::ClientBuilder::new(credential).build()`.
3. Obtain a sub-client for the resource you want (e.g. `repositories_client()`).
4. Call the operation method. Mandatory parameters are positional arguments; optional parameters
   are set via builder methods. Finalize and send the request by `.await`ing the builder
   (the builder implements `IntoFuture`).

### Example

```rust
use anyhow::Result;
use azure_devops_rust_api::git;
use azure_devops_rust_api::Credential;
use azure_identity::AzureCliCredential;
use std::env;

#[tokio::main]
async fn main() -> Result<()> {
    // Authenticate using the Azure CLI
    let credential = Credential::from_token_credential(AzureCliCredential::new(None)?);

    let organization = env::var("ADO_ORGANIZATION").expect("Must define ADO_ORGANIZATION");
    let project = env::var("ADO_PROJECT").expect("Must define ADO_PROJECT");

    // Create a git client
    let git_client = git::ClientBuilder::new(credential).build();

    // List all repositories in the project
    let repos = git_client
        .repositories_client()
        .list(organization, project)
        .await?
        .value;

    for repo in repos.iter() {
        println!("{}", repo.name);
    }
    println!("{} repos found", repos.len());

    Ok(())
}
```

See [examples/git_repo_list.rs](examples/git_repo_list.rs) for the full runnable version.

## Available features

Each Azure DevOps API area is a separate, opt-in feature. Enable only the ones you need.

| Feature | Description |
|---|---|
| `git` | Repositories, pull requests, commits, branches |
| `build` | Build definitions and pipeline runs |
| `pipelines` | YAML pipelines |
| `release` | Release definitions and deployments |
| `wit` | Work items and queries |
| `test` / `test_plan` / `test_results` | Test management |
| `artifacts` | Azure Artifacts feeds and packages |
| `artifacts_download` | Higher-level Universal Package download client (see below) |
| `wiki` | Wikis and pages |
| `graph` | Users, groups, and memberships |
| `core` | Projects and teams |
| `distributed_task` | Agent pools, task groups, environments |
| `policy` | Branch policies |
| `security` | Security namespaces and ACLs |
| `search` | Code, work item, and wiki search |
| `tfvc` | Team Foundation Version Control |
| `profile` | User profiles |
| `audit` | Audit log |
| `hooks` | Service hooks |
| `status` | Service health |
| `work` | Boards, sprints, and backlogs |

See the `[features]` section of [Cargo.toml](Cargo.toml) for the complete list.

## Artifact downloads

In addition to the auto-generated REST API wrappers, the crate includes a higher-level
`artifacts_download` module for downloading [Universal Packages](https://learn.microsoft.com/en-us/azure/devops/artifacts/quickstarts/universal-packages?view=azure-devops)
from Azure Artifacts.

Unlike the other modules, `artifacts_download` is not a thin wrapper around a single REST
endpoint. It implements the full dedup-based download protocol: discovering service URLs,
fetching package metadata, resolving blob IDs, downloading and decompressing content chunks,
and reassembling them into files on disk.

Enable it with the `artifacts_download` feature:

```toml
[dependencies]
azure_devops_rust_api = { version = "0.37.0", features = ["artifacts_download"] }
```

See [examples/download_artifact.rs](examples/download_artifact.rs) for a full usage example.

Run the example:

```sh
cargo run --example download_artifact --features="artifacts_download" -- \
    --feed <feed> --name <package-name> --version <version> --path <output-dir>
```

## Examples

The [examples/](examples/) directory contains runnable examples for most API areas.

Run an example:

```sh
cargo run --example git_repo_get --features="git" -- <repo-name>
```

If you omit the required `--features` flag you will get a helpful error message listing what
is needed.

## Minimum supported Rust version (MSRV)

This crate requires Rust **1.80.0** or later.

## Issue reporting

Please raise bugs and feature requests via [GitHub Issues](https://github.com/microsoft/azure-devops-rust-api/issues).

If the issue is in the underlying OpenAPI spec (wrong types, missing fields, incorrect paths),
it is better raised against [vsts-rest-api-specs](https://github.com/MicrosoftDocs/vsts-rest-api-specs),
as fixes there will automatically flow into this crate on the next regeneration.

## Useful links

- [Azure DevOps REST API Reference](https://learn.microsoft.com/en-us/rest/api/azure/devops/)
- [vsts-rest-api-specs](https://github.com/MicrosoftDocs/vsts-rest-api-specs)
- [API docs (docs.rs)](https://docs.rs/azure_devops_rust_api)