Batteries
Analytics
Register the events you care about, log them, and count them back. Types are declared up front so a typo is an error at the call that made it rather than a dimension that reads zero forever.
Every call below goes to the address in your
SAASIE_ANALYTICS_URL
environment variable, with
Authorization: Bearer <token>. Read both from
the environment — they are injected, and hardcoding either is how
an app breaks when the platform moves.
See getting the credential.
POST
/v1/analytics/events
Log events
Every event's type must be registered, and every property must be one that type declared. Both are 400s rather than silently-stored data, because an event nobody meant to send is worse than one that was refused.
Request body
| Field | Type | |
|---|
events* |
object[] |
— |
200 — How many were stored
| Field | Type | |
|---|
recorded* |
number |
How many events were stored. |
remainingToday* |
number |
How many more this Saasie may log before the daily cap. |
When it does not work
400 | An unregistered type, or an undeclared property |
401 | Missing or invalid service token |
403 | The Saasie is stopped |
429 | The daily event cap is spent |
501 | This Saasie has no analytics storage |
502 | The analytics cluster is unreachable |
POST
/v1/analytics/query
Count events over a range
A constrained query, never SQL: a type, a range, a bucket size, and optionally one declared property to split by. That is enough to draw a chart and small enough that nothing a caller sends becomes part of a statement.
Request body
| Field | Type | |
|---|
type* |
string |
— |
since* |
integer | string |
Start of the range, inclusive. Epoch milliseconds or ISO. |
until |
integer | string |
End of the range, exclusive. Left out, it is now. |
interval |
string |
hour · day · week · month, defaults to day |
groupBy |
string |
A property of this type to split the counts by. It must be one the type declared. |
200 — Counts per bucket
| Field | Type | |
|---|
type* |
string |
— |
interval* |
string |
hour · day · week · month |
since* |
number |
— |
until* |
number |
— |
groupBy* |
string | null |
— |
buckets* |
object[] |
— |
total* |
number |
— |
When it does not work
400 | Unknown type, undeclared groupBy, or too wide a range |
401 | Missing or invalid service token |
501 | This Saasie has no analytics storage |
502 | The analytics cluster is unreachable |
POST
/v1/analytics/types
Register an event type
Idempotent, so an app can call it at boot without checking. Registering an existing type replaces the properties it declares — which is how a type gains one, and also how an event carrying an old property starts being refused.
Request body
| Field | Type | |
|---|
name* |
string |
The event type, e.g. signup. Registering it again updates it. |
properties |
object |
The properties every event of this type may carry, and what each one means. An event carrying anything else is refused. defaults to {} |
200 — The type, as it now stands
| Field | Type | |
|---|
name* |
string |
— |
properties* |
object |
— |
createdAt* |
number |
— |
updatedAt* |
number |
— |
When it does not work
400 | The name or a property name is not usable |
401 | Missing or invalid service token |
403 | The Saasie is stopped |
GET
/v1/analytics/types
What this Saasie has registered
200 — Every registered type
| Field | Type | |
|---|
types* |
object[] |
— |
When it does not work
401 | Missing or invalid service token |