docs: measurements + measurement-jobs resources (chat#1796 contract)

Merged
SW
4mo ago
+273-446

The contract (docs-first) for chat#1796 — consolidate the /research play-count surface into two REST resources. Head of the docs → api → skill merge order.

New endpoints

  • GET /research/tracks/{id}/measurements — the measurement series; granularity=daily (series), aggregate=run_rate&window=365d (derived projection). Replaces track/historic-stats + track/playcount-deltas.
  • GET /research/albums/{id}/measurements?latest=true — latest per-track counts. Replaces playcounts.
  • POST /research/measurement-jobs { scope, source: "current" | "historical" } → 202 + pollable GET /research/measurement-jobs/{id}. current replaces snapshots; historical is the backfill seed (replaces the never-built backfill verb).

Deprecations

track/historic-stats, track/playcount-deltas, playcounts, snapshots marked deprecated: true with a migration note pointing at the new resource.

Changes

  • api-reference/openapi/research.json — 4 path operations + 8 schemas (additive diff; the 7 "deletions" are descriptions re-prefixed with the deprecation note).
  • 4 frontmatter-only MDX pages + docs.json Catalog nav entries.

Validation

  • mintlify openapi-check → valid.
  • All 98 $refs resolve; 4 new paths present; 4 legacy ops flagged deprecated.

Summary by cubic

Consolidates the research play-count APIs into two REST resources and a single ingest job. Removes the old RPC endpoints and aligns with chat#1796.

  • New Features

    • GET /api/research/tracks/{id}/measurements — daily series; supports aggregate=run_rate&window=365d. {id} accepts ISRC or Spotify track id.
    • GET /api/research/albums/{id}/measurements?latest=true — latest per-track counts for an album.
    • POST /api/research/measurement-jobs (source: "current" | "historical") — create ingest jobs; poll status via GET /api/tasks/runs.

  • Migration

    • Replace GET /api/research/track/historic-stats with GET /api/research/tracks/{id}/measurements?granularity=daily.
    • Replace GET /api/research/track/playcount-deltas with GET /api/research/tracks/{id}/measurements?aggregate=run_rate.
    • Replace GET /api/research/playcounts with GET /api/research/albums/{id}/measurements?latest=true.
    • Replace POST /api/research/snapshots with POST /api/research/measurement-jobs (source:"current"). Use source:"historical" for deep backfill.

Summary by CodeRabbit

  • New Features

    • Added track measurement endpoints providing time-series data with optional aggregation options
    • Added album measurement endpoints for latest per-track measured counts
    • Added ability to enqueue asynchronous measurement jobs for current and historical data capture

  • Documentation

    • Updated API reference documentation to reflect new measurement endpoints
    • Reorganized Research API navigation structure