Standardize API documentation and update canary logs

[ShadowInCache]

Summary by CodeRabbit

• Documentation

  • Standardized API endpoint path notation across all documentation
  • Enhanced API reference with consistent request/response/error formatting
  • Clarified HTTP status codes and error scenarios for all endpoints

• New Features

  • Added synthetic canary demo routes for monitoring
  • Expanded API endpoint documentation coverage

• Infrastructure

  • Redesigned Grafana monitoring dashboard with updated metrics visualization
  • Updated Grafana datasource and provisioning configuration

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f000ef06-7be8-4b25-989d-64c3cba7e0fa

📥 Commits

Reviewing files that changed from the base of the PR and between b443eda and 21c85ab.

⛔ Files ignored due to path filters (3)

• logs/nginx/access.log is excluded by !**/*.log
• logs/nginx/error.log is excluded by !**/*.log
• security/canary_failures.log is excluded by !**/*.log

📒 Files selected for processing (13)

• DECISIONS.md
• DEPLOYMENT_CHECKLIST.md
• QUICKREF.md
• README.md
• README_GHOSTLINK.md
• docker-compose.yml
• docs/API_REFERENCE.md
• docs/FAILURE_EDGE_CASES.md
• docs/README.md
• grafana/dashboards/ghostlink.json
• grafana/provisioning/dashboards/dashboard.yml
• grafana/provisioning/datasources/prometheus.yml
• security/canary_state.env

---

📝 Walkthrough

Walkthrough

This pull request standardizes API endpoint documentation across multiple files, converting path parameter notation from angle-bracket style (<id>) to curly-brace style ({id}). It restructures API reference templates with consistent sections (Request Example, Success Response, Error Responses), updates Docker Compose Grafana configuration, substantially redesigns the Grafana dashboard with new panels and metrics focus, and updates canary state values.

Changes

Cohort / File(s)	Summary
API Endpoint Documentation README.md, DECISIONS.md, docs/API_REFERENCE.md, docs/FAILURE_EDGE_CASES.md	Updated endpoint path notation from <id>/<short_code> to {id}/{short_code} format; standardized API reference template structure with consistent "Request Example", "Success Response", and "Error Responses" labels across all endpoint sections.
API & Deployment Guides DEPLOYMENT_CHECKLIST.md, QUICKREF.md	Updated checklist and quick-reference examples to use curly-brace placeholders and named path parameters (e.g., {short_code}, {id}); removed port numbers from example URLs; enhanced response descriptions with clarified status codes and conditions (e.g., 403 for ownership mismatch, 410 for inactive links).
README & Documentation Index README_GHOSTLINK.md, docs/README.md	Restructured README_GHOSTLINK.md from inline endpoint examples to a consolidated "Endpoint Matrix" table with canonical references to docs/API_REFERENCE.md; updated docs/README.md to document the standardized template convention.
Docker Compose & Grafana Provisioning docker-compose.yml, grafana/provisioning/datasources/prometheus.yml, grafana/provisioning/dashboards/dashboard.yml	Updated Grafana service to use grafana/grafana:latest image, added admin username configuration, changed volume and mount paths (e.g., grafana_data → grafana-data), and updated provisioning datasource uid from prometheus to ghostlink-prometheus with editable flag enabled.
Grafana Dashboard grafana/dashboards/ghostlink.json	Redesigned dashboard from "GhostLink Platform Overview" to "GhostLink Command Center"; replaced comprehensive metrics set with focused panels for canary checks, link health distribution, feature flags, release footprint, and suspicious client tracking; updated Prometheus datasource references and added PromQL safety fallbacks.
Canary Metrics security/canary_state.env	Updated canary telemetry values: increased success total (680 → 851) and failure total (5 → 39), advanced last run timestamp, and revised per-check latency metrics.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~35 minutes

Possibly related PRs

• Added some .md files #2: Overlapping modifications to API reference documentation and endpoint template standardization across docs/API_REFERENCE.md and README_GHOSTLINK.md.

Poem

🐰 Curly braces now embrace our API's way,
Documentation standardized, neat as fresh hay,
Dashboards redesigned for command and control,
Every endpoint shines with a well-templated soul! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}