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
- A stored value is never overwritten. A revision is a new version with a later known time. How the platform thinks shows it.
- No request deletes a stored value.
- A read as of a past moment never loses a value and never changes one; it may gain some. A value can be stored late with the earlier time its source published it, as after a feeder's outage. "A stored value is never changed" does not mean "the same read answers the same for ever": write your model to take the data it is given. How the platform thinks gives the example.
- A series keeps its name, kind, unit and description. They are set when the series is first stored and are not changed after.
- A namespace belongs to one feeder for good. The
series under
entsoe.will not one day come from someone else.
The platform's indicators
- A released version never changes. The same call to it answers the same, with the same inputs, parameters, defaults and ranges, for as long as 3.x lasts. A change that would alter any answer, a fix included, is a new version.
- Every released version stays through 3.x.
GET /v1/indicatorslists, for each indicator, every version it computes. - The answer says which version computed.
"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
- The code of a version never changes. Each upload is a new version, numbered from 1.
- A number is never used twice. If an owner deletes a version, or deletes a function and uses its name again, the versions count on from where they stopped, so a version you named never comes to mean other code.
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
- Every failure has one shape: a problem (RFC 9457),
with
type,title,status,detailandinstance, and the platform'scode,classanddetails(Errors). Until 3.2.15 it haderror,code,messageanddetails. - The code is for programs, and is stable. The detail is for people, and its words may change.
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.
- 3.2.14: a missing value must say why, in a
statuscolumn; a column the interface does not name is refused. - 3.2.15: errors became problems
(Errors): an error's
messageis nowdetailand itserrorisclass; a receipt holds its refusal asproblem, where it helderror. A heartbeat that tells a failure in the old form is still read.
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:
| Release | Added | An older client |
|---|---|---|
| 3.2.5 | Fields: a read of a run's log returns the run with it. | Ignores the new fields. |
| 3.2.8 | A request: GET /v1/meta. | Never calls it. |
| 3.2.10 | A 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:
- New fields in any answer, and new entries in a list, such as a new series in the catalog or a new indicator.
- New requests.
- New error codes. Decide by the code where you know it and by the status where you do not.
- New events in the stream. Ignore an event whose name you do not know.
- New versions of an indicator or of a person's function. A call that names no version takes the newest, so its answer may change on the day a new one is released. A call that names its version is not moved.
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.
- The reference follows the platform. The ingestor's
reference said that its
/healthcould answer status 503. It never did;/readydoes. In 3.2.9 the reference was corrected. No client saw a difference. - The platform follows its reference. Until 3.2.10 a compute whose
stepwas a number, where a duration as text is asked for, was computed as if no step were given. It is now refused withinvalid_request. A client that sent such a step was getting an answer it had not asked for; it now learns so.
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.
| Version | Looks like | Where you see it | Says |
|---|---|---|---|
| The product's | 3.2.16 |
GET /v1/meta, as product |
The release that runs. |
| A unit's | 3.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's | 3.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
- In the release notes. What changed lists, release by release and unit by unit, what someone outside the team can see or use. It is published with the release it describes, on this site.
- By the platform itself.
GET /v1/metaand the About page say which release runs and when each unit last changed. If the read API's version,units.api.version, is the one you last tested against, the read API has not changed. - In the references. The read API's reference and the ingestor's are served by the platform they describe, so they describe the release that runs.
A client that lasts
Seven habits, each for a reason given above.
- Ignore fields you do not know. Read the fields you need by name; never fail on an extra one.
- Branch on
code, never ondetail. - Handle a code you do not know by its status.
- Name the version of every indicator and function whose answer you keep.
- Name
as_ofwherever a result must be had again later. - 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.
- Check
GET /v1/metawhen something behaves differently, and read What changed for that release.