Update API docs: forecasts and self-contained metadata reference - #3589
Merged
Conversation
Contributor
|
Warning Review limit reached
More reviews will be available in 13 minutes and 16 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThis PR comprehensively updates API documentation for the AirQo platform, introducing a versioned Forecast API with daily and hourly PM2.5 forecasting endpoints, a new Metadata API for discovering monitoring infrastructure, and realigning all related reference material and client-facing guides. ChangesAPI Documentation Overhaul
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/docs-website/docs/api/reference/error-codes.md (1)
8-8:⚠️ Potential issue | 🟠 Major | ⚡ Quick winThe page currently contradicts itself on “consistent” error shape.
Line 8 states consistency, but the documented schemas differ (
status/codevssuccess/error). Please explicitly split error formats by API family (e.g., Devices/Analytics vs Forecast) to prevent incorrect client-side parsing assumptions.Also applies to: 12-30, 114-122
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/docs-website/docs/api/reference/error-codes.md` at line 8, The doc claims a single "consistent" error shape but shows two different schemas; update error-codes.md to explicitly split and document the error formats per API family (e.g., Devices/Analytics use {status, code, message, data} while Forecast uses {success, error, details} or whatever the actual shapes are), add clear headings "Devices/Analytics error format" and "Forecast error format", provide canonical JSON schema examples for each, and add a short note calling out the difference so clients know which format to expect for each API family; ensure the examples match the real response fields used by the implementations referenced in the repo.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/docs-website/docs/api/forecasts/overview.md`:
- Around line 18-20: The fenced code blocks containing the endpoint snippets
(for example the block with "GET /api/v2/predict/daily-forecasting/") are
missing a language tag and trigger markdownlint MD040; update each such
triple-backtick fence (including the other endpoint/snippet fences in the same
document) to use an explicit language like ```http or ```text so the snippets
render and pass docs CI. Locate the fences around the GET/endpoint examples and
prepend the language identifier to each opening ``` fence.
- Line 53: The docs declare wind_from_direction as "degrees" but examples and
the field reference use compass strings like "NE"; change the canonical
type/units for wind_from_direction to a compass/cardinal-direction string (e.g.,
"N","NE","E", etc.) throughout the doc so examples, the field description and
any sample payloads match; update the top-level schema entry for
wind_from_direction, both example blocks, and the field reference text to
specify "compass" or "cardinal-direction string" instead of "degrees".
In `@src/docs-website/docs/api/reference/metadata.md`:
- Around line 20-22: The fenced code blocks showing HTTP endpoints (e.g., the
block containing "GET /api/v2/devices/metadata/grids?token={SECRET_TOKEN}" and
the other similar endpoint blocks listed) are missing a language tag; add a
language identifier such as ```http (or ```text) to each of those fenced blocks
so markdownlint MD040 is satisfied—update every occurrence mentioned (lines
showing GET ... endpoints at the listed locations) to start with ```http and
leave the block content unchanged.
---
Outside diff comments:
In `@src/docs-website/docs/api/reference/error-codes.md`:
- Line 8: The doc claims a single "consistent" error shape but shows two
different schemas; update error-codes.md to explicitly split and document the
error formats per API family (e.g., Devices/Analytics use {status, code,
message, data} while Forecast uses {success, error, details} or whatever the
actual shapes are), add clear headings "Devices/Analytics error format" and
"Forecast error format", provide canonical JSON schema examples for each, and
add a short note calling out the difference so clients know which format to
expect for each API family; ensure the examples match the real response fields
used by the implementations referenced in the repo.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 655200eb-c711-4040-9a1c-f12c57717366
📒 Files selected for processing (7)
src/docs-website/docs/api/for-cities/intro.mdsrc/docs-website/docs/api/for-partners/intro.mdsrc/docs-website/docs/api/forecasts/overview.mdsrc/docs-website/docs/api/reference/error-codes.mdsrc/docs-website/docs/api/reference/finding-ids.mdsrc/docs-website/docs/api/reference/metadata.mdsrc/docs-website/docs/api/reference/response-structure.md
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the public API documentation site (src/docs-website) to (1) align Forecast API docs with the current predict-service endpoints/response shapes and (2) replace a retiring external Metadata documentation link with a new, fully self-contained internal Metadata API reference.
Changes:
- Reworked Forecast API docs to use
/api/v2/predict/daily-forecasting/and/api/v2/predict/hourly-forecasting/, with updated response examples and field references. - Added a new internal
Metadata APIreference page and rewired “Finding IDs” + partner/city intro pages to link to it instead ofdocs.airqo.net. - Added/updated reference content for validation errors and forecast response structure.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| src/docs-website/docs/api/reference/response-structure.md | Updates the forecast response reference to match the current forecasting endpoints and schema pointers. |
| src/docs-website/docs/api/reference/metadata.md | Adds a new internal, self-contained Metadata API reference (grids/cohorts/sites/devices/locations). |
| src/docs-website/docs/api/reference/finding-ids.md | Replaces retired external metadata links with internal Metadata API guidance and adds a discovery endpoint quick table. |
| src/docs-website/docs/api/reference/error-codes.md | Adds a documented 400 error example for mutually exclusive forecast identifiers. |
| src/docs-website/docs/api/forecasts/overview.md | Major rewrite of Forecast API docs including daily/hourly endpoints, examples, and field reference tables. |
| src/docs-website/docs/api/for-partners/intro.md | Updates partner onboarding docs to reflect cohort forecasting availability and new metadata references. |
| src/docs-website/docs/api/for-cities/intro.md | Updates city onboarding docs with forecast endpoints and internal metadata references. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+52
to
+54
| "wind_speed": "m/s", | ||
| "wind_from_direction": "degrees", | ||
| "forecast_confidence": "%" |
Comment on lines
+147
to
+149
| "wind_speed": "m/s", | ||
| "wind_from_direction": "degrees", | ||
| "forecast_confidence": "%" |
Comment on lines
+59
to
+63
| "site_id": "site-123", | ||
| "site_name": "Kampala Central", | ||
| "site_latitude": 0.3476, | ||
| "site_longitude": 32.5825 | ||
| }, |
Comment on lines
+154
to
+158
| "site_id": "site-123", | ||
| "site_name": "Kampala Central", | ||
| "site_latitude": 0.3476, | ||
| "site_longitude": 32.5825 | ||
| }, |
Comment on lines
+207
to
+211
| "scope": { | ||
| "type": "grid", | ||
| "id": "grid-123", | ||
| "grid_id": "grid-123" | ||
| }, |
Comment on lines
+203
to
205
| ### Scope Metadata Returned | ||
|
|
||
| ```json |
| "units": { "pm2_5": "ug/m3", "forecast_confidence": "%" }, | ||
| "forecasts": [ | ||
| { | ||
| "site_details": { "site_id": "site-123", "site_name": "Kampala Central" }, |
Comment on lines
+78
to
+81
| --- | ||
|
|
||
| --- | ||
|
|
Fix all issues raised in inline review comments across the forecast and
reference documentation pages.
- Add `http` language tag to all bare fenced code blocks in
forecasts/overview.md (3 blocks) and reference/metadata.md (13 blocks)
to satisfy markdownlint MD040 and ensure correct syntax highlighting
- Correct `units.wind_from_direction` value from "degrees" to "compass"
in both the daily and hourly response examples; the predict microservice
converts raw degree values to compass strings (e.g. "NE", "SW") before
returning them, making the old unit label internally inconsistent with
the example payloads and field reference table
- Replace placeholder `site_id: "site-123"` with a realistic 24-char hex
ID in forecasts/overview.md (daily + hourly blocks) and
reference/response-structure.md to match the documented ID format
- Replace placeholder scope IDs ("grid-123") with a realistic 24-char hex
ID in the scope metadata example in forecasts/overview.md
- Add envelope clarification note before the scope metadata JSON block so
readers understand the object is nested inside `{ "success": true,
"data": { ... } }`, consistent with all other response examples
- Split the "consistent error response" claim in reference/error-codes.md
into two explicitly documented formats — Devices/Analytics API
(`status`, `message`, `code`) and Forecast API (`success`, `message`,
`error`) — each with a field table, replacing the contradictory single
"consistent" description
- Remove duplicate horizontal rule (`---` appearing twice consecutively)
in reference/finding-ids.md
…eferenceError
The link display text contained a bare {GRID_ID} placeholder which MDX
evaluated as a JSX expression, throwing ReferenceError at static site
generation. Moved the path template into an adjacent code span instead.
Contributor
|
New azure docs changes available for preview here |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Pull Request
📋 Description
What does this PR do?
Updates the AirQo public API documentation (
src/docs-website) across two major areas:Forecast API (
/api/v2/predict/):forecasts/overview.mdwith the current endpoint paths (/predict/daily-forecasting/,/predict/hourly-forecasting/), accurate request parameters (site_id,grid_id,cohort_id), and full response examples for both daily and hourly formatspm2_5_q10/pm2_5_q90), complete meteorological fields, wind direction as compass string, AQI category table, trend messages, the optionalscopedisambiguation parameter, and a caching/update frequency notereference/response-structure.mdto reference the current endpoint paths and updated response shapefor-partners/intro.md: cohort-based forecasting is now supported (was incorrectly marked ❌)for-cities/intro.mdwith accurate forecast parameter note and a direct link to the Forecast API page400 Bad Requesterror entry inreference/error-codes.mdfor the mutual-exclusion validation onsite_id/grid_id/cohort_idfor-cities/intro.mdandfor-partners/intro.mdMetadata API (new self-contained reference):
reference/metadata.md— a complete, internally-hosted Metadata API reference covering grids, cohorts, sites, devices, and locations, with endpoint definitions, query parameters, example responses, device category tables, and common workflow guidesdocs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadataacrossreference/finding-ids.md,for-cities/intro.md, andfor-partners/intro.md, replacing each with deep links into the new internal pagereference/finding-ids.mdwith API-call-based discovery instructions and a new quick-reference table of all eight metadata discovery endpointsWhy is this change needed?
The external metadata documentation link (
docs.airqo.net/airqo-rest-api-documentation) is being retired. Keeping references to it would leave users hitting a dead end. All discovery content is now self-contained within this documentation site.The forecast documentation also referenced deprecated endpoint paths (
/predict/hourly-forecast,/predict/daily-forecast) and an outdated response structure, and incorrectly stated that cohort-based forecasting was unavailable — all of which have been corrected to match the current predict microservice behaviour.🔗 Related Issues
🔄 Type of Change
🏗️ Affected Services
Microservices changed: N/A — documentation only
Documentation files changed:
src/docs-website/docs/api/forecasts/overview.md— full rewritesrc/docs-website/docs/api/reference/metadata.md— new filesrc/docs-website/docs/api/reference/finding-ids.md— expandedsrc/docs-website/docs/api/reference/response-structure.md— forecast section updatedsrc/docs-website/docs/api/reference/error-codes.md— new 400 error entrysrc/docs-website/docs/api/for-cities/intro.md— forecast + metadata links updatedsrc/docs-website/docs/api/for-partners/intro.md— forecast availability corrected, metadata links updated🧪 Testing
Test summary:
Manual review of all changed files. Verified zero remaining references to the retired external metadata URL (
grepconfirmed clean). Cross-checked all internal links between pages for correctness. Endpoint paths, parameters, and response examples validated against the live predict microservice (/src/predict/api/routes.py,prediction.py) and device-registry metadata routes (/src/device-registry/routes/v2/metadata.routes.js,grids.routes.js,cohorts.routes.js).💥 Breaking Changes
Documentation-only changes. No API behaviour, code, or configuration is modified.
📝 Additional Notes
/predict/hourly-forecast,/predict/daily-forecast) still exist in the microservice for backward compatibility but are not documented here; the new-forecastingvariants are the current public-facing API.reference/metadata.mdpage covers only publicly accessible metadata endpoints (no JWT-scoped admin endpoints). Internal/tenant-scoped device-registry routes are intentionally excluded from public docs.cohort_idsupport correction infor-partners/intro.mdaligns with actual microservice behaviour —cohort_idis a valid parameter on both/predict/daily-forecasting/and/predict/hourly-forecasting/.✅ Checklist
Summary by CodeRabbit