57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# Migrating from the hand-written `@umami/api-client`
|
|
|
|
The previous client (`umami-software/api-client`) maintained every endpoint by hand. This package
|
|
is generated from Umami's OpenAPI contract and replaces it. That repository will be archived once
|
|
this package is stable.
|
|
|
|
## What changed
|
|
|
|
| Before | After |
|
|
| ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
| `getClient({ apiEndpoint, apiKey, userId, secret })` | `new UmamiClient({ baseUrl, apiKey, token })` |
|
|
| Methods return `{ ok, data, status, error }` | Methods return the response body and **throw** `UmamiApiError` on non-2xx |
|
|
| Positional arguments `getWebsiteStats(websiteId, params)` | Single object `getWebsiteStats({ websiteId, ...params })` (positional still works for common analytics methods, see below) |
|
|
| `getWebsites()` | `listWebsites()` (`getWebsites` kept as a deprecated alias) |
|
|
| `userId` + `secret` mint a token client-side | Removed. Mint the token yourself and pass `token`. |
|
|
|
|
## Errors
|
|
|
|
```ts
|
|
// before
|
|
const { ok, data, error } = await client.getWebsiteStats(id, params);
|
|
if (!ok) { … }
|
|
|
|
// after
|
|
try {
|
|
const data = await client.getWebsiteStats({ websiteId: id, ...params });
|
|
} catch (error) {
|
|
if (isUmamiApiError(error)) { error.status; error.code; }
|
|
}
|
|
```
|
|
|
|
## Compatibility overloads
|
|
|
|
To ease upgrades these methods still accept the old positional form:
|
|
|
|
`getWebsite`, `updateWebsite`, `deleteWebsite`, `getWebsiteActive`, `getWebsiteDateRange`,
|
|
`getWebsiteStats`, `getWebsitePageviews`, `getWebsiteMetrics`, `getWebsiteExpandedMetrics`,
|
|
`getWebsiteEvents`, `getWebsiteEventSeries`, `getWebsiteEventStats`, `getEventData`,
|
|
`getEventDataStats`, `getEventDataProperties`, `getEventDataValues`, `getWebsiteSessions`,
|
|
`getWebsiteSessionStats`, `getWebsiteSession`, `getWebsiteSessionActivity`,
|
|
`getWebsiteSessionProperties`, `getWebsiteReports`.
|
|
|
|
They are deprecated and will be removed in the next major release. The object form is canonical.
|
|
|
|
## Method names
|
|
|
|
Method names are OpenAPI `operationId`s. Most match the old names (`getWebsiteStats`,
|
|
`getWebsiteFunnelStats`, `getRealtime`, `createTeam`, …). Endpoints that were not in the old client are
|
|
now available automatically. Endpoints under `/api/admin`, `/api/config`, `/api/dashboard` and
|
|
other internal routes are intentionally excluded.
|
|
|
|
## Triage of the old surface
|
|
|
|
- **Kept**: websites, analytics, events, sessions, session data, reports, teams, users, boards,
|
|
links, pixels, shares, account (`me`), auth, two-factor, tracking (`send`, `batch`, `record`).
|
|
- **Dropped**: admin endpoints (not part of the public API), client-side token minting.
|