Skip to content

Commit 614cf7c

Browse files
johnbattyclaude
johnbatty
and
claude
authored
Improve readme (#775)
* Release 0.36.0 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Improve README: badges, quickstart, auth section, feature table, MSRV, updated links Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Clean up CHANGELOG Removed duplicate entry for README improvements. --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 802c8cf commit 614cf7c

3 files changed

Lines changed: 140 additions & 97 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.36.0]
11+
1012
### Added
1113

1214
- New `artifacts_download` higher-level module for downloading Universal Packages from Azure DevOps Artifacts.
@@ -15,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1517
### Changes
1618

1719
- Update `azure_core` and `azure_identity` to 0.34.
20+
- Improved README: added badges, quickstart guide, authentication section, feature table, MSRV, and updated links to learn.microsoft.com.
1821

1922
## [0.35.0]
2023

@@ -677,7 +680,8 @@ breaking changes over previous versions.
677680

678681
- Initial release.
679682

680-
[Unreleased]: https://github.com/microsoft/azure-devops-rust-api/compare/0.35.0...HEAD
683+
[Unreleased]: https://github.com/microsoft/azure-devops-rust-api/compare/0.36.0...HEAD
684+
[0.36.0]: https://github.com/microsoft/azure-devops-rust-api/compare/0.35.0...0.36.0
681685
[0.35.0]: https://github.com/microsoft/azure-devops-rust-api/compare/0.34.0...0.35.0
682686
[0.34.0]: https://github.com/microsoft/azure-devops-rust-api/compare/0.33.0...0.34.0
683687
[0.33.0]: https://github.com/microsoft/azure-devops-rust-api/compare/0.32.0...0.33.0

‎azure_devops_rust_api/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
[package]
55
name = "azure_devops_rust_api"
6-
version = "0.35.0"
6+
version = "0.36.0"
77
edition = "2021"
88
authors = ["John Batty <johnbatty@microsoft.com>"]
99
description = "Rust API library for Azure DevOps"

‎azure_devops_rust_api/README.md‎

Lines changed: 134 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,161 @@
11
# Azure DevOps Rust API
22

3-
## Overview
3+
[![Crates.io](https://img.shields.io/crates/v/azure_devops_rust_api.svg)](https://crates.io/crates/azure_devops_rust_api)
4+
[![docs.rs](https://docs.rs/azure_devops_rust_api/badge.svg)](https://docs.rs/azure_devops_rust_api)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
46

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

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

9-
The crate contains [38 modules](https://docs.rs/azure_devops_rust_api/latest/azure_devops_rust_api/#modules)
11+
## Getting started
1012

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

13-
### Usage overview
15+
```toml
16+
[dependencies]
17+
azure_devops_rust_api = { version = "0.36.0", features = ["git", "pipelines"] }
18+
```
1419

15-
The crate has many features/modules, but the general approach is similar for all:
20+
2. Set environment variables:
1621

17-
- Obtain an authentication credential
18-
- See [examples](examples/utils/mod.rs) for how to do this using the `azure_identity` crate
19-
- Create a client for the feature/module that you want to use
20-
- Normally you need to create a client for the top-level module that you want to use,
21-
(e.g. `git_client`), and then one for the submodule (e.g. `repositories_client`).
22-
- Use the client to make operation requests
23-
- Each operation has zero or more mandatory parameters and zero or more optional parameters.
24-
Mandatory parameters are passed as parameters on the operation request method. Optional
25-
parameters may be provided by calling methods on the "builder" object returned by the
26-
operation request method. The builder object is finalized by invoking `await`, which transforms
27-
the builder into a Future (via the `IntoFuture` trait) and awaits the response.
22+
```sh
23+
export ADO_ORGANIZATION=<organization-name>
24+
export ADO_PROJECT=<project-name>
25+
```
2826

29-
### Code example
27+
3. Authenticate — see the [Authentication](#authentication) section below.
3028

31-
Example usage (from [examples/git_repo_list.rs](examples/git_repo_list.rs)):
29+
4. Create a client and call the API — see the [Usage](#usage) section and [examples](examples/).
3230

33-
```rust
34-
// Get authentication credential either from a PAT ("ADO_TOKEN")
35-
// or via the az cli.
36-
let credential = utils::get_credential()
31+
## Authentication
3732

38-
// Get ADO configuration via environment variables
39-
let organization = env::var("ADO_ORGANIZATION")
40-
.expect("Must define ADO_ORGANIZATION");
41-
let project = env::var("ADO_PROJECT")
42-
.expect("Must define ADO_PROJECT");
33+
Two authentication methods are supported:
4334

44-
// Create a git client
45-
let git_client = git::ClientBuilder::new(credential).build();
35+
### Azure CLI (recommended for development)
4636

47-
// Get all repositories in the specified organization/project
48-
let repos = git_client
49-
.repositories_client()
50-
.list(organization, project)
51-
.await?
52-
.value;
37+
Run `az login` once, then:
5338

54-
// Output repo names
55-
for repo in repos.iter() {
56-
println!("{}", repo.name);
57-
}
58-
println!("{} repos found", repos.len());
39+
```rust
40+
use azure_devops_rust_api::Credential;
41+
use azure_identity::AzureCliCredential;
42+
43+
let cli_credential = AzureCliCredential::new(None)?;
44+
let credential = Credential::from_token_credential(cli_credential);
5945
```
6046

61-
[Individual modules in the API](https://docs.rs/azure_devops_rust_api/latest/azure_devops_rust_api/#modules) are enabled via Rust [`features`](https://doc.rust-lang.org/cargo/reference/features.html).
47+
### Personal Access Token (PAT)
6248

63-
See the `features` section of [Cargo.toml](Cargo.toml) for the full list of features.
49+
Create a [PAT](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate)
50+
with the minimum required scopes and a short expiry, then:
6451

65-
Example application `Cargo.toml` dependency spec showing how to specify desired features:
52+
```rust
53+
use azure_devops_rust_api::Credential;
6654

67-
```toml
68-
[dependencies]
69-
...
70-
azure_devops_rust_api = { version = "0.35.0", features = ["git", "pipelines"] }
55+
let token = std::env::var("ADO_TOKEN").expect("Must define ADO_TOKEN");
56+
let credential = Credential::from_pat(token);
7157
```
7258

73-
## Examples
59+
> **Note:** Treat PATs like passwords — grant only the minimum required scopes and set a short expiry.
7460
75-
See [examples](examples/) directory.
61+
## Usage
7662

77-
Define environment variables:
63+
All modules follow the same pattern:
7864

79-
```sh
80-
export ADO_ORGANIZATION=<organization-name>
81-
export ADO_PROJECT=<project-name>
82-
```
65+
1. Obtain a `Credential` (see [Authentication](#authentication) above).
66+
2. Create a top-level client via `<module>::ClientBuilder::new(credential).build()`.
67+
3. Obtain a sub-client for the resource you want (e.g. `repositories_client()`).
68+
4. Call the operation method. Mandatory parameters are positional arguments; optional parameters
69+
are set via builder methods. Finalize and send the request by `.await`ing the builder
70+
(the builder implements `IntoFuture`).
8371

84-
To run the examples you need to provide authentication credentials either via:
72+
### Example
8573

86-
- The `az` CLI, where you just need to have authenticated by running `az login` before running the examples.
87-
- A [Personal Access Token (PAT)](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate), provided via the environment variable `ADO_TOKEN`
88-
> Note: A personal access token contains your security credentials for Azure DevOps.
89-
> A PAT identifies you, your accessible organizations, and scopes of access.
90-
> As such, they're as critical as passwords, so you should treat them the same way.
91-
> When creating a PAT only grant it the minimum required scopes, and set the expiry time to be short.
74+
```rust
75+
use anyhow::Result;
76+
use azure_devops_rust_api::git;
77+
use azure_devops_rust_api::Credential;
78+
use azure_identity::AzureCliCredential;
79+
use std::env;
9280

93-
Run the example via `cargo run --example`. You will need to enable the features required
94-
by the example. If you don't specify the necessary features you do get a helpful error
95-
message.
81+
#[tokio::main]
82+
async fn main() -> Result<()> {
83+
// Authenticate using the Azure CLI
84+
let credential = Credential::from_token_credential(AzureCliCredential::new(None)?);
9685

97-
Example:
86+
let organization = env::var("ADO_ORGANIZATION").expect("Must define ADO_ORGANIZATION");
87+
let project = env::var("ADO_PROJECT").expect("Must define ADO_PROJECT");
9888

99-
```sh
100-
cargo run --example git_repo_get --features="git" <repo-name>
89+
// Create a git client
90+
let git_client = git::ClientBuilder::new(credential).build();
91+
92+
// List all repositories in the project
93+
let repos = git_client
94+
.repositories_client()
95+
.list(organization, project)
96+
.await?
97+
.value;
98+
99+
for repo in repos.iter() {
100+
println!("{}", repo.name);
101+
}
102+
println!("{} repos found", repos.len());
103+
104+
Ok(())
105+
}
101106
```
102107

108+
See [examples/git_repo_list.rs](examples/git_repo_list.rs) for the full runnable version.
109+
110+
## Available features
111+
112+
Each Azure DevOps API area is a separate, opt-in feature. Enable only the ones you need.
113+
114+
| Feature | Description |
115+
|---|---|
116+
| `git` | Repositories, pull requests, commits, branches |
117+
| `build` | Build definitions and pipeline runs |
118+
| `pipelines` | YAML pipelines |
119+
| `release` | Release definitions and deployments |
120+
| `wit` | Work items and queries |
121+
| `test` / `test_plan` / `test_results` | Test management |
122+
| `artifacts` | Azure Artifacts feeds and packages |
123+
| `artifacts_download` | Higher-level Universal Package download client (see below) |
124+
| `wiki` | Wikis and pages |
125+
| `graph` | Users, groups, and memberships |
126+
| `core` | Projects and teams |
127+
| `distributed_task` | Agent pools, task groups, environments |
128+
| `policy` | Branch policies |
129+
| `security` | Security namespaces and ACLs |
130+
| `search` | Code, work item, and wiki search |
131+
| `tfvc` | Team Foundation Version Control |
132+
| `profile` | User profiles |
133+
| `audit` | Audit log |
134+
| `hooks` | Service hooks |
135+
| `status` | Service health |
136+
| `work` | Boards, sprints, and backlogs |
137+
138+
See the `[features]` section of [Cargo.toml](Cargo.toml) for the complete list.
139+
103140
## Artifact downloads
104141

105142
In addition to the auto-generated REST API wrappers, the crate includes a higher-level
106-
`artifacts_download` module for downloading [Universal Packages](https://docs.microsoft.com/en-us/azure/devops/artifacts/universal-packages/universal-packages-overview)
143+
`artifacts_download` module for downloading [Universal Packages](https://learn.microsoft.com/en-us/azure/devops/artifacts/universal-packages/universal-packages-overview)
107144
from Azure Artifacts.
108145

109146
Unlike the other modules, `artifacts_download` is not a thin wrapper around a single REST
110-
endpoint. It implements the full dedup-based download protocol used by Azure Artifacts:
111-
discovering service URLs, fetching package metadata, resolving blob IDs, downloading and
112-
decompressing content chunks, and reassembling them into files on disk.
147+
endpoint. It implements the full dedup-based download protocol: discovering service URLs,
148+
fetching package metadata, resolving blob IDs, downloading and decompressing content chunks,
149+
and reassembling them into files on disk.
113150

114151
Enable it with the `artifacts_download` feature:
115152

116153
```toml
117154
[dependencies]
118-
azure_devops_rust_api = { version = "0.35.0", features = ["artifacts_download"] }
155+
azure_devops_rust_api = { version = "0.36.0", features = ["artifacts_download"] }
119156
```
120157

121-
Example usage (from [examples/download_artifact.rs](examples/download_artifact.rs)):
122-
123-
```rust
124-
let client = artifacts_download::ClientBuilder::new(credential).build();
125-
126-
let metadata = client
127-
.download_universal_package(
128-
&organization,
129-
&project,
130-
&feed,
131-
&package_name,
132-
&version,
133-
&output_path,
134-
)
135-
.await?;
136-
137-
println!(
138-
"Downloaded {} v{} ({} bytes) to {:?}",
139-
package_name, metadata.version, metadata.package_size, output_path
140-
);
141-
```
158+
See [examples/download_artifact.rs](examples/download_artifact.rs) for a full usage example.
142159

143160
Run the example:
144161

@@ -147,11 +164,33 @@ cargo run --example download_artifact --features="artifacts_download" -- \
147164
--feed <feed> --name <package-name> --version <version> --path <output-dir>
148165
```
149166

167+
## Examples
168+
169+
The [examples/](examples/) directory contains runnable examples for most API areas.
170+
171+
Run an example:
172+
173+
```sh
174+
cargo run --example git_repo_get --features="git" -- <repo-name>
175+
```
176+
177+
If you omit the required `--features` flag you will get a helpful error message listing what
178+
is needed.
179+
180+
## Minimum supported Rust version (MSRV)
181+
182+
This crate requires Rust **1.80.0** or later.
183+
150184
## Issue reporting
151185

152-
If you find any issues then please raise them via [Github](https://github.com/microsoft/azure-devops-rust-api/issues).
186+
Please raise bugs and feature requests via [GitHub Issues](https://github.com/microsoft/azure-devops-rust-api/issues).
187+
188+
If the issue is in the underlying OpenAPI spec (wrong types, missing fields, incorrect paths),
189+
it is better raised against [vsts-rest-api-specs](https://github.com/MicrosoftDocs/vsts-rest-api-specs),
190+
as fixes there will automatically flow into this crate on the next regeneration.
153191

154192
## Useful links
155193

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

0 commit comments

Comments
 (0)