Commit aebe493dcd
Verified · cmc
Layout: unified · split
API.md +33 −3
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | # API Reference |
| 2 | 2 | |
| 3 | `srht-contrib` exposes a small HTTP JSON API for health checks, contribution calendar reads, manual polling, and tracked repository management. | |
| 3 | `srht-contrib` exposes a small HTTP JSON API for health checks, contribution calendar reads, manual polling, and optional tracked repository management. | |
| 4 | 4 | |
| 5 | 5 | Base URL examples: |
| 6 | 6 | |
| @@ -45,13 +45,21 @@ Contribution ranges: | ||
| 45 | 45 | - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates. |
| 46 | 46 | - Public contribution reads also register the actor for background indexing. A first lookup may therefore return an empty graph while the scheduler catches up. |
| 47 | 47 | |
| 48 | Background polling: | |
| 49 | ||
| 50 | - When `ENABLE_SCHEDULER=true`, the service runs one poll immediately at startup and then continues polling on `POLL_INTERVAL_SECONDS`. | |
| 51 | - The scheduler always seeds `DEFAULT_ACTOR` as a known actor. | |
| 52 | - Public contribution reads register additional actors for later background polling. | |
| 53 | - Manual polling remains available through `POST /api/contributions/poll`. | |
| 54 | ||
| 48 | 55 | Repository names: |
| 49 | 56 | |
| 50 | 57 | - Repository create/update accepts either: |
| 51 | 58 | - shorthand `repo-name` |
| 52 | 59 | - canonical `~owner/repo-name` |
| 53 | 60 | - Stored repository names are normalized to canonical `~owner/repo-name` form. |
| 54 | - Tracked repositories are optional force-includes for git polling; owned repositories are auto-discovered per actor. | |
| 61 | - Git polling auto-discovers repositories owned by the actor through SourceHut. | |
| 62 | - Tracked repositories are optional force-includes for git polling; they are not required for normal owned-repository discovery. | |
| 55 | 63 | |
| 56 | 64 | ## Health |
| 57 | 65 | |
| @@ -97,6 +105,12 @@ Rules: | ||
| 97 | 105 | - Or provide both `from` and `to` |
| 98 | 106 | - Do not combine `year` with `from`/`to` |
| 99 | 107 | |
| 108 | Behavior notes: | |
| 109 | ||
| 110 | - This endpoint resolves aliases to a canonical actor before querying data. | |
| 111 | - This endpoint also registers the actor for background indexing and updates the actor's `last_requested_at` timestamp. | |
| 112 | - The response is always immediate; it does not wait for SourceHut polling to finish. | |
| 113 | ||
| 100 | 114 | Example by year: |
| 101 | 115 | |
| 102 | 116 | ```bash |
| @@ -139,6 +153,12 @@ Response fields: | ||
| 139 | 153 | - `count` integer contribution count for the day |
| 140 | 154 | - `score` float weighted score for the day |
| 141 | 155 | |
| 156 | Indexing state semantics: | |
| 157 | ||
| 158 | - `pending`: the actor is known but has not completed a successful poll yet | |
| 159 | - `indexed`: at least one successful poll has completed for the actor | |
| 160 | - `error`: the most recent poll attempt for the actor failed | |
| 161 | ||
| 142 | 162 | Possible errors: |
| 143 | 163 | |
| 144 | 164 | - `400 Bad Request` for invalid or conflicting date input |
| @@ -169,6 +189,11 @@ Query parameters: | ||
| 169 | 189 | - `from` string `YYYY-MM-DD`, optional |
| 170 | 190 | - `to` string `YYYY-MM-DD`, optional |
| 171 | 191 | |
| 192 | Behavior notes: | |
| 193 | ||
| 194 | - This endpoint has the same actor-registration and alias-resolution behavior as the calendar endpoint. | |
| 195 | - This endpoint returns immediately and does not block on SourceHut polling. | |
| 196 | ||
| 172 | 197 | Example: |
| 173 | 198 | |
| 174 | 199 | ```bash |
| @@ -247,6 +272,11 @@ Response fields: | ||
| 247 | 272 | - `inserted_events` integer: number of newly inserted normalized events |
| 248 | 273 | - `services` array of strings: currently `["todo", "git"]` |
| 249 | 274 | |
| 275 | Behavior notes: | |
| 276 | ||
| 277 | - Manual polling also updates the actor's indexing metadata. | |
| 278 | - Git polling auto-discovers the actor's owned repositories and unions in any configured tracked repositories. | |
| 279 | ||
| 250 | 280 | Possible errors: |
| 251 | 281 | |
| 252 | 282 | - `401 Unauthorized` if the API key is missing or invalid |
| @@ -272,7 +302,7 @@ Example `502`: | ||
| 272 | 302 | |
| 273 | 303 | All repository endpoints are protected and require `X-API-Key`. |
| 274 | 304 | |
| 275 | Tracked repositories are used by git polling. Each repository is associated with an actor and stored in canonical `~owner/repo` form. | |
| 305 | Tracked repositories are optional force-includes for git polling. Each repository is associated with an actor and stored in canonical `~owner/repo` form. | |
| 276 | 306 | |
| 277 | 307 | ### `GET /api/repositories` |
| 278 | 308 | |