Commit aebe493dcd
Verified · cmc
Layout: unified · split
API.md +33 −3
| @@ -1,6 +1,6 @@ | |||
| 1 | # API Reference | 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 | Base URL examples: | 5 | Base URL examples: |
| 6 | 6 | ||
| @@ -45,13 +45,21 @@ Contribution ranges: | |||
| 45 | - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates. | 45 | - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates. |
| 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. | 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 | Repository names: | 55 | Repository names: |
| 49 | 56 | ||
| 50 | - Repository create/update accepts either: | 57 | - Repository create/update accepts either: |
| 51 | - shorthand `repo-name` | 58 | - shorthand `repo-name` |
| 52 | - canonical `~owner/repo-name` | 59 | - canonical `~owner/repo-name` |
| 53 | - Stored repository names are normalized to canonical `~owner/repo-name` form. | 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 | ## Health | 64 | ## Health |
| 57 | 65 | ||
| @@ -97,6 +105,12 @@ Rules: | |||
| 97 | - Or provide both `from` and `to` | 105 | - Or provide both `from` and `to` |
| 98 | - Do not combine `year` with `from`/`to` | 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 | Example by year: | 114 | Example by year: |
| 101 | 115 | ||
| 102 | ```bash | 116 | ```bash |
| @@ -139,6 +153,12 @@ Response fields: | |||
| 139 | - `count` integer contribution count for the day | 153 | - `count` integer contribution count for the day |
| 140 | - `score` float weighted score for the day | 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 | Possible errors: | 162 | Possible errors: |
| 143 | 163 | ||
| 144 | - `400 Bad Request` for invalid or conflicting date input | 164 | - `400 Bad Request` for invalid or conflicting date input |
| @@ -169,6 +189,11 @@ Query parameters: | |||
| 169 | - `from` string `YYYY-MM-DD`, optional | 189 | - `from` string `YYYY-MM-DD`, optional |
| 170 | - `to` string `YYYY-MM-DD`, optional | 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 | Example: | 197 | Example: |
| 173 | 198 | ||
| 174 | ```bash | 199 | ```bash |
| @@ -247,6 +272,11 @@ Response fields: | |||
| 247 | - `inserted_events` integer: number of newly inserted normalized events | 272 | - `inserted_events` integer: number of newly inserted normalized events |
| 248 | - `services` array of strings: currently `["todo", "git"]` | 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 | Possible errors: | 280 | Possible errors: |
| 251 | 281 | ||
| 252 | - `401 Unauthorized` if the API key is missing or invalid | 282 | - `401 Unauthorized` if the API key is missing or invalid |
| @@ -272,7 +302,7 @@ Example `502`: | |||
| 272 | 302 | ||
| 273 | All repository endpoints are protected and require `X-API-Key`. | 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 | ### `GET /api/repositories` | 307 | ### `GET /api/repositories` |
| 278 | 308 | ||