Calculated Metrics

Create a calculated metric

Creates a calculated metric of the account: a column the widgets of that integration can draw like any other, and that /v1/fields publishes from then on.

THREE KINDS, AND THE BODY CARRIES THE BLOCK OF ONE. expression is a formula over the metrics of the integration; function aggregates one metric over a day, a week or a month; filtered reads one metric through a saved filter of the same integration. The two blocks that are not this metric's kind are left out or sent as null, which is what a read publishes for them.

THE IDS OF A FORMULA ARE CHECKED, which is stricter than the application and is deliberate: the editor calls a token a metric as soon as it starts with the prefix of an integration, so a retired id is saved and drawn as an empty column for ever. Here every token that is not an operator, a parenthesis or a number has to be a metric /v1/fields publishes for the integration, and anything else is refused by name. The rest of the rules are the editor's, one for one: a formula does not begin with an operator or with ')', does not end with an operator or with '(', carries no forbidden pair of consecutive tokens, carries at least one metric, and balances its parentheses.

integration_id, type and level cannot be changed afterwards. The metric is born as the account's own: is_system_defined and the signature of a catalogue definition are never written by this API.

if_version is not accepted, and the call is never confirmed: its inverse is /v1/calculated-metrics/delete.

Refusals: 400 for the framework, the body and the formula, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND when a filtered metric names a filter that is not this account's.

A definition written through this API is not visible to an application window that is already open: the page has to be reloaded before the same definition is edited there.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/calculated-metrics/create

Request

Base URL: https://api.reportingninja.com/v1
URL: https://api.reportingninja.com/v1/calculated-metrics/create
Auth: HTTP bearer

Request body

namestring required

How the definition is listed in the account. 2 to 50 characters, with no character above the Basic Multilingual Plane.

display_namestring nullable

What a widget draws as the column header. Left out or null on a creation, it is the name.

internal_notesstring nullable

A note for the account's own staff, at most 250 characters. An empty string takes it away.

integration_idstring required

The integration the metric belongs to. It cannot be changed once the metric exists.

levelstring nullable

The data view the metric is read in. Required for the integrations capabilities lists under calculated_metrics.level_required_for, written by the platform for the ones under calculated_metrics.level_fixed_for -- which accept the value a read publishes for them and nothing else -- and refused for the rest. The values it takes are the data views /v1/integrations/detail publishes for the integration. It cannot be changed once the metric exists.

type'expression' | 'function' | 'filtered' required

Which of the three kinds it is. It cannot be changed once the metric exists: each kind is stored in columns of its own.

calculated_metric_keystring

The key the row already has. Published by /v1/calculated-metrics/get and written by nothing. It is accepted here so the object a read answers can be sent straight back as a body; the key is ignored and the answer carries a READ_ONLY_FIELD_IGNORED warning naming it.

integrationstring

The name of a data source this API publishes no integration_id for, which a read answers instead of integration_id. Published by /v1/calculated-metrics/get and written by nothing. It is accepted here so the object a read answers can be sent straight back as a body; the key is ignored and the answer carries a READ_ONLY_FIELD_IGNORED warning naming it.

is_system_definedboolean

Published by /v1/calculated-metrics/get and written by nothing. It is accepted here so the object a read answers can be sent straight back as a body; the key is ignored and the answer carries a READ_ONLY_FIELD_IGNORED warning naming it.

not_expressible_reasonstring nullable

not_expressible_messagestring nullable

dry_runboolean

Validate everything and write nothing.

idempotency_keystring

Replays the answer of an identical call for 24 hours.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.