|
| 1 | +--- |
| 2 | +name: use-rest-api |
| 3 | +description: Use the Torrust Tracker REST API. Covers authentication, all endpoints (stats, metrics, torrents, auth keys, whitelist), and making announce/scrape requests to verify API behaviour. Triggers on "use API", "test API", "call REST API", "query API", "API endpoint", "curl tracker", "tracker client", "announce request", or "verify API". |
| 4 | +metadata: |
| 5 | + author: torrust |
| 6 | + version: "1.0" |
| 7 | +--- |
| 8 | + |
| 9 | +# Use REST API |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +A running tracker with the REST API enabled. The default development config starts the API on port 1212: |
| 14 | + |
| 15 | +```bash |
| 16 | +cargo run |
| 17 | +``` |
| 18 | + |
| 19 | +## Skill Links |
| 20 | + |
| 21 | +This skill depends on these artifacts. If any of them change, review this skill. |
| 22 | + |
| 23 | +- `share/default/config/tracker.development.sqlite3.toml` |
| 24 | +- `packages/axum-rest-api-server/src/v1/middlewares/auth.rs` |
| 25 | +- `packages/axum-rest-api-server/src/routes.rs` |
| 26 | +- `packages/axum-rest-api-server/src/v1/routes.rs` |
| 27 | + |
| 28 | +Use the marker `skill-link: use-rest-api` in affected artifacts. |
| 29 | + |
| 30 | +## Authentication |
| 31 | + |
| 32 | +All API endpoints (except `/api/health_check`) require an access token. |
| 33 | + |
| 34 | +### Header Method (preferred) |
| 35 | + |
| 36 | +```bash |
| 37 | +curl -H "Authorization: Bearer MyAccessToken" http://localhost:1212/api/v1/stats |
| 38 | +``` |
| 39 | + |
| 40 | +### Query Parameter Method |
| 41 | + |
| 42 | +```bash |
| 43 | +curl "http://localhost:1212/api/v1/stats?token=MyAccessToken" |
| 44 | +``` |
| 45 | + |
| 46 | +### Configuration |
| 47 | + |
| 48 | +Tokens are defined in the TOML config file under `[http_api.access_tokens]`: |
| 49 | + |
| 50 | +```toml |
| 51 | +[http_api.access_tokens] |
| 52 | +admin = "MyAccessToken" |
| 53 | +``` |
| 54 | + |
| 55 | +Every token in the map has identical permissions — the label (`admin`) is just a human-readable name. |
| 56 | + |
| 57 | +## Endpoints |
| 58 | + |
| 59 | +All endpoints use `http://localhost:1212` as base (default dev config). |
| 60 | + |
| 61 | +### Health Check |
| 62 | + |
| 63 | +| Method | Endpoint | Auth | |
| 64 | +| ------ | ------------------- | ----- | |
| 65 | +| GET | `/api/health_check` | ❌ No | |
| 66 | + |
| 67 | +```bash |
| 68 | +curl -s http://localhost:1212/api/health_check |
| 69 | +``` |
| 70 | + |
| 71 | +### Stats |
| 72 | + |
| 73 | +| Method | Endpoint | Auth | |
| 74 | +| ------ | ----------------- | ------ | |
| 75 | +| GET | `/api/v1/stats` | ✅ Yes | |
| 76 | +| GET | `/api/v1/metrics` | ✅ Yes | |
| 77 | + |
| 78 | +```bash |
| 79 | +curl -s http://localhost:1212/api/v1/stats -H "Authorization: Bearer MyAccessToken" |
| 80 | +curl -s http://localhost:1212/api/v1/metrics -H "Authorization: Bearer MyAccessToken" |
| 81 | +``` |
| 82 | + |
| 83 | +### Auth Keys |
| 84 | + |
| 85 | +| Method | Endpoint | Auth | |
| 86 | +| ------ | ------------------------------------ | ------ | |
| 87 | +| POST | `/api/v1/key/{seconds_valid_or_key}` | ✅ Yes | |
| 88 | +| DELETE | `/api/v1/key/{seconds_valid_or_key}` | ✅ Yes | |
| 89 | +| GET | `/api/v1/keys/reload` | ✅ Yes | |
| 90 | +| POST | `/api/v1/keys` | ✅ Yes | |
| 91 | + |
| 92 | +### Whitelist |
| 93 | + |
| 94 | +| Method | Endpoint | Auth | |
| 95 | +| ------ | ------------------------------- | ------ | |
| 96 | +| POST | `/api/v1/whitelist/{info_hash}` | ✅ Yes | |
| 97 | +| DELETE | `/api/v1/whitelist/{info_hash}` | ✅ Yes | |
| 98 | +| GET | `/api/v1/whitelist/reload` | ✅ Yes | |
| 99 | + |
| 100 | +### Torrents |
| 101 | + |
| 102 | +| Method | Endpoint | Auth | |
| 103 | +| ------ | ----------------------------- | ------ | |
| 104 | +| GET | `/api/v1/torrent/{info_hash}` | ✅ Yes | |
| 105 | +| GET | `/api/v1/torrents` | ✅ Yes | |
| 106 | + |
| 107 | +## Making Announce Requests with the Tracker Client |
| 108 | + |
| 109 | +The `tracker_client` binary can make BitTorrent announce requests to verify the tracker is working. |
| 110 | + |
| 111 | +### UDP Announce |
| 112 | + |
| 113 | +```bash |
| 114 | +cargo run -p torrust-tracker-client --bin tracker_client -- udp announce udp://localhost:6969/announce 0123456789abcdef0123456789abcdef01234567 |
| 115 | +``` |
| 116 | + |
| 117 | +### HTTP Announce |
| 118 | + |
| 119 | +```bash |
| 120 | +cargo run -p torrust-tracker-client --bin tracker_client -- http announce http://localhost:7070/announce 0123456789abcdef0123456789abcdef01234567 |
| 121 | +``` |
| 122 | + |
| 123 | +### Scrape |
| 124 | + |
| 125 | +```bash |
| 126 | +cargo run -p torrust-tracker-client --bin tracker_client -- udp scrape udp://localhost:6969/announce 0123456789abcdef0123456789abcdef01234567 |
| 127 | +``` |
| 128 | + |
| 129 | +Output defaults to JSON. Use `--format text` for human-readable output. |
| 130 | + |
| 131 | +## Verification Workflow |
| 132 | + |
| 133 | +After making an announce request, verify the API reflects the activity: |
| 134 | + |
| 135 | +1. Check stats changed: |
| 136 | + |
| 137 | + ```bash |
| 138 | + curl -s http://localhost:1212/api/v1/stats -H "Authorization: Bearer MyAccessToken" |
| 139 | + ``` |
| 140 | + |
| 141 | + Expect `torrents` and `seeders` to increase. |
| 142 | + |
| 143 | +2. Check metrics changed: |
| 144 | + |
| 145 | + ```bash |
| 146 | + curl -s http://localhost:1212/api/v1/metrics -H "Authorization: Bearer MyAccessToken" |
| 147 | + ``` |
| 148 | + |
| 149 | + Expect protocol-specific counters to increase. |
| 150 | + |
| 151 | +3. Check tracker console logs show the request was received: |
| 152 | + |
| 153 | + ```text |
| 154 | + active_peers_total=1 active_torrents_total=1 |
| 155 | + ``` |
0 commit comments