Specs

What stays the same

A program you write today should run next month. This page says what the platform holds fixed, what it may add, and where to look when something does change. It states only what is decided.

The platform is in a testing phase. Until it is declared stable, a release may change an interface or break a client, without notice ahead of it. No one outside the team builds on it yet, and the team may still change the requests under /v1 where it must. A correction that makes the platform refuse what it used to let pass may come in any release. What is on this page is how the platform is built and what it aims to keep; it is not yet a promise. What changed lists every such change, release by release: read it before you take a new release for granted.

The guide for readers of data: 1. How the platform thinks · 2. Reading data and building on it · 3. What stays the same · 4. What changed

One example

Suppose that in March you compute a rolling mean of a price for a report, with the platform's indicator rolling-mean, version 2. In September an auditor asks you to produce the same figures again.

Two things could spoil the answer. The indicator's arithmetic could have been improved since March. And the prices could have been corrected.

The platform closes both doors. A released version of an indicator never changes: an improvement is version 3, and version 2 goes on computing as it did. A correction to a price is stored as a new version beside the old value, never over it. So the same call, naming version 2 and the March moment as as_of, computes by the same rule on the same values.

That is the pattern of everything on this page: the platform changes by adding, and you name what you built on.

What does not change

The record

The platform's indicators

"The same" means the same for the same values read. Name as_of as well as the version, and a later revision cannot move the answer. One thing outside the platform still can: a change in a time zone's rules, which reaches the days it concerns.

People's models and indicators

A person's function is its owner's all the same. The owner may deprecate a version, delete a deprecated one, or delete the function, and an operator may suspend a version. Name the version you rely on, and expect unknown_version, unknown_model or version_suspended one day.

Errors

The ingestor's interface

If you also push data, through the ingestor, the same holds as for reading: while the platform is in its testing phase, a release may change this interface too. Each such change is listed under "Breaking" in What changed, with what to change in a client.

What stays true through every such change: a stored value is never changed, a batch sent again is stored once, and a client must ignore fields it does not know. From version 4.0 the interface only grows, and a change a client could trip on gets a new path.

What may be added

The read API grows from release to release. Three examples from 3.2:

ReleaseAddedAn older client
3.2.5Fields: a read of a run's log returns the run with it.Ignores the new fields.
3.2.8A request: GET /v1/meta.Never calls it.
3.2.10A field: each series' card in the catalog.Ignores it.

None of these touched a program that read only what it knew. So write yours that way. Expect, at any release and without a word beforehand:

Corrections

Sometimes the platform does one thing and its reference says another. Then one of the two is corrected, and the correction is listed in What changed. Two examples show both directions.

A correction of the second kind can stop a request that used to pass. That is why the last section asks you to send exactly what the reference asks for.

The versions you meet

Several things carry a version. They are easy to confuse, so here is each with where you see it.

VersionLooks likeWhere you see itSays
The product's3.2.16 GET /v1/meta, as product The release that runs.
A unit's3.2.8 GET /v1/meta, under units A unit is a part one team releases: the read API, the ingestor, the runtime. Its version is the product's version in which it last changed.
The path's/v1 Every request of the read API The generation of the interface.
A reference's3.2.10 The bar of the read API's reference and of the ingestor's The release in which that reference last changed. It moves only when the reference does, so do not use it to tell what runs: GET /v1/meta says that.
An indicator's"2" GET /v1/indicators; every compute's answer The rule that computed.
A function's"1" GET /v1/functions; the path of every call, and its answer The upload that ran.

To learn what a platform runs, ask it:

curl -sS -H "Authorization: Bearer $BFF_TOKEN" "$BFF_URL/v1/meta"

It answers in this shape:

{
  "product": "3.2.9",
  "units": {
    "api": {"version": "3.2.9", "says": "The read API"},
    "ingestor": {"version": "3.2.9", "says": "Checks each push and writes it"},
    "runner": {"version": "3.2.8", "says": "Hands runs of people's functions to the workers"}
  }
}

(Three of the units are shown.) The answer may also name the commit that was deployed, and when. Anyone signed in may ask. A platform that was started by hand, with no release written down, answers "product": null and no units.

How a change is announced

A client that lasts

Seven habits, each for a reason given above.

  1. Ignore fields you do not know. Read the fields you need by name; never fail on an extra one.
  2. Branch on code, never on detail.
  3. Handle a code you do not know by its status.
  4. Name the version of every indicator and function whose answer you keep.
  5. Name as_of wherever a result must be had again later.
  6. Send exactly what the reference asks for: times with their offset, durations as text, no field it does not list. What is passed over today may be refused tomorrow, as a correction.
  7. Check GET /v1/meta when something behaves differently, and read What changed for that release.