docs(api): deprecate report routes and document migration compatibility
This commit is contained in:
Mike Cao committed
1 parent
7c4406bad0
commit
4fbaa5300d
46 files changed
+564
-72
No files matched your search
@@ -0,0 +1,118 @@
|
||||
# Report API migration
|
||||
|
||||
The website analytics APIs replace report execution endpoints. Analytics use GET; saved
|
||||
funnels and goals have dedicated resource routes. The application and MCP use the new routes.
|
||||
The report table and existing definition IDs are retained. No database migration is required.
|
||||
|
||||
## Calculation endpoints
|
||||
|
||||
Paths in the replacement column are relative to `/api/websites/{websiteId}`.
|
||||
|
||||
| Legacy POST endpoint | Replacement GET endpoint(s) |
|
||||
| --- | --- |
|
||||
| `/api/reports/attribution` | `/attribution` |
|
||||
| `/api/reports/breakdown` | `/breakdown` |
|
||||
| `/api/reports/funnel` | `/funnels/stats` or `/funnels/{funnelId}/stats` |
|
||||
| `/api/reports/goal` | `/goals/stats` or `/goals/{goalId}/stats` |
|
||||
| `/api/reports/heatmap` | `/heatmaps` |
|
||||
| `/api/reports/journey` | `/journeys` |
|
||||
| `/api/reports/performance` | `/performance/stats`, `/performance/chart`, `/performance/metrics` |
|
||||
| `/api/reports/retention` | `/retention` |
|
||||
| `/api/reports/revenue` | Existing `/revenue/stats`, `/revenue/chart`, `/revenue/metrics` |
|
||||
| `/api/reports/utm` | `/utm/metrics` |
|
||||
|
||||
New requests use `startAt` and `endAt` in epoch milliseconds, with optional `timezone`, `unit`,
|
||||
and existing filter parameters. Dates are normalized through the shared website filter pipeline,
|
||||
including reset dates and account history limits. The report envelope and discriminator are gone.
|
||||
Use a single date range; do not send separate filter dates and calculation dates.
|
||||
|
||||
`steps` on funnel previews and `fields` on breakdowns are JSON strings, URL-encoded normally.
|
||||
Other criteria are individual query parameters. For example:
|
||||
|
||||
```ts
|
||||
await client.getWebsiteFunnelStats({
|
||||
websiteId,
|
||||
startAt,
|
||||
endAt,
|
||||
timezone: 'UTC',
|
||||
window: 60,
|
||||
steps: JSON.stringify([
|
||||
{ type: 'path', value: '/pricing' },
|
||||
{ type: 'event', value: 'signup' },
|
||||
]),
|
||||
});
|
||||
```
|
||||
|
||||
The calculation criteria remain feature-specific: journeys accept `steps`, `startStep`,
|
||||
`endStep`, and `eventType`; attribution accepts `model`, `type`, and `step`; goal previews
|
||||
accept `type` and `value`; heatmaps accept `urlPath` and `mode`. See `/openapi.json` for contracts.
|
||||
|
||||
Performance stats return the old `summary` object directly. Performance chart returns
|
||||
`{ chart }`. Performance metrics return a single dimension array; `type` is `path`, `title`,
|
||||
`device`, or `browser`. Chart and metrics accept `metric` (`lcp`, `inp`, `cls`, `fcp`, `ttfb`).
|
||||
Stats calculate all metrics independently of the chart selection. The same percentile SQL is
|
||||
used by legacy and new handlers.
|
||||
|
||||
UTM metrics return `{ utm, views }[]` for one `type`: `utm_source`, `utm_medium`, `utm_campaign`,
|
||||
`utm_term`, or `utm_content`. The existing pageview counting rules, empty-value exclusion,
|
||||
and 50-row limit are preserved. UTM board widgets request only their configured dimension.
|
||||
|
||||
Revenue endpoints retain their existing contracts. MCP `get_revenue` composes stats, chart,
|
||||
and four dimension requests, preserving its previous output and comparison data.
|
||||
|
||||
## Saved definitions
|
||||
|
||||
| Method | Path (relative to website) | Purpose |
|
||||
| --- | --- | --- |
|
||||
| GET | `/funnels` | List definitions, with pagination/search |
|
||||
| POST | `/funnels` | Create `{ name, description?, parameters }` |
|
||||
| GET | `/funnels/{funnelId}` | Read definition |
|
||||
| POST | `/funnels/{funnelId}` | Update `{ name, description?, parameters }` |
|
||||
| DELETE | `/funnels/{funnelId}` | Delete definition |
|
||||
| GET | `/funnels/{funnelId}/stats` | Calculate saved criteria with supplied dates/filters |
|
||||
| GET | `/funnels/stats` | Calculate supplied criteria without saving |
|
||||
|
||||
Goals expose the same structure under `/goals`. Website and definition type are fixed by the
|
||||
route and cannot be changed in an update body. IDs, names, descriptions, and board `reportId`
|
||||
references are preserved. Saved stats validate stored criteria and require both definition access
|
||||
and analytics-section access. Unsupported or malformed legacy criteria return 400 for stats;
|
||||
the definition remains readable/editable through the compatibility API.
|
||||
|
||||
Section-based sharing is preserved. Heatmaps remain authenticated-only. New definition lists
|
||||
support type-specific section sharing and exclude deleted websites. Legacy report list routes
|
||||
retain their original, differing authentication behavior during the transition.
|
||||
|
||||
## Compatibility and removal gate
|
||||
|
||||
All legacy calculation and saved-report routes remain callable with their existing contracts.
|
||||
OpenAPI marks them deprecated; generated SDK methods carry `@deprecated` and remain available.
|
||||
Legacy handlers and new feature routes call the same SQL functions; no internal HTTP forwarding
|
||||
is involved. Legacy calculation envelopes and date precedence remain unchanged.
|
||||
|
||||
Do not remove generic report CRUD solely because the current UI only saves funnels and goals.
|
||||
Before scheduling removal:
|
||||
|
||||
1. Audit persisted report counts by type, including older definitions outside funnel/goal.
|
||||
2. Audit malformed funnel/goal criteria that stricter feature APIs cannot calculate.
|
||||
3. Decide how users can export, edit, migrate, or retain every other saved type.
|
||||
4. Confirm external API clients have replacements for their operations and payloads.
|
||||
5. Announce a compatibility window and the breaking release that will remove legacy routes.
|
||||
6. Verify the application, boards, SDK examples, and MCP no longer call legacy endpoints.
|
||||
|
||||
No removal date or version is scheduled by this change. The metadata and documentation prepare
|
||||
the deprecation; they do not announce a release externally or delete historical records.
|
||||
|
||||
## Validation
|
||||
|
||||
Unit tests cover GET serialization, invalid structured input, normalized ranges, permission
|
||||
checks, definition website/type mismatches, immutable update scope, SQL dataset separation for
|
||||
PostgreSQL and ClickHouse, cache keys, SDK requests, MCP composition, and deprecation metadata.
|
||||
|
||||
`tests/api/report-migration.spec.ts` exercises legacy/new result parity, saved-definition
|
||||
lifecycles, shared access, and split datasets against the existing disposable API test stack.
|
||||
It is intended to run in both database modes. Do not point it at a development or production
|
||||
database: the API suite seeds and mutates test data. This migration was developed without a
|
||||
running disposable API server; live backend parity remains a release verification step.
|
||||
|
||||
Regenerate and verify contracts with `pnpm generate:api`, `pnpm openapi:check`, and
|
||||
`pnpm check:api:client`. Build packages before their tests so MCP resolves the current API client.
|
||||
Reference in new issue
Block a user