A Version That Is a Date
Seven providers in this series pin an interface version and only one does it with a date in a header. It is the best of the seven, for a reason that has nothing to do with the format and everything to do with who bears the cost of a change.
Every connector in this series names a version of the interface it was written against. They do it in five different ways, and the differences are usually treated as trivia. They are not — the mechanism decides who pays when the provider changes something, and one of the seven has arranged it so the cost falls where it should.
Five ways to say which version
| Where the version lives | Looks like | What it means when the provider changes |
|---|---|---|
| A number in the path | A major version segment | Change is rare and large; you migrate when they retire it |
| A precise version in the path | A major and minor number | Finer control, and more versions to track |
| A date in a header | The day that behaviour was fixed | Behaviour is frozen at a moment; you move when you choose |
| A version given to a client library | A constructor argument | The library decides, and you inherit its schedule |
| Nothing at all | No version anywhere | Whatever they ship today is what you get |
The last row is the one to avoid and it is more common than it should be. An unversioned integration has outsourced its own behaviour, and nothing about it will look different on the day that becomes a problem.
A version number tells you which release you asked for. A date tells you which day you asked to be treated as.
Why a date is the good version
A date says something a number cannot: the behaviour of this interface as it stood on that day. It is not a release name, it is a snapshot.
That has two practical consequences. The provider can improve the interface continuously without asking anybody to migrate, because every change lands under a new date and existing callers keep the behaviour they were built against. And you can see immediately how far behind you are, in a unit everybody understands, without knowing anything about their release conventions.
Compare a version number. Is a jump from one to the next large or small? It depends entirely on the provider's habits, which you have to learn. A date needs no such knowledge — two years is two years, and it is legible to somebody who has never seen the product.
And why the header rather than the address
A version is a property of how you want to be spoken to, not of what you are asking for. The address names the resource; the terms of the conversation belong in the headers, alongside the credential and the content type.
That is not merely tidy. An address containing a version number tends to acquire a second one, because there is no natural place to put a finer-grained change — which is exactly how a provider ends up with a major version in the path and a minor one in a header anyway.
It also means the version travels on every request without being threaded through every address you construct. One place to set it, one place to change it, and no possibility of one call being pinned while another is not.
The obligation that comes with pinning
A pinned version is a promise you make to yourself, and it has to be kept.
The interface behaves as it did on that date until the provider retires it, which they eventually will. So there is a maintenance task: read what changed, adjust, move the date, test.
That obligation is the feature, not the price. The alternative is not an absence of maintenance — it is the same work, arriving unscheduled, discovered through a symptom rather than a note. A scheduled upgrade you can plan is a much better event than a behaviour change you have to diagnose from the wrong end.
It is worth noticing which failures this prevents. Not the loud ones — a removed endpoint fails immediately and gets fixed. The ones pinning protects you from are the quiet changes: a field that starts arriving in a different shape, a default that flips, a limit that tightens. Those produce wrong data rather than errors.
A title that is not a string
One detail from the same connector, because it is the kind that produces a wrong list and no error.
A database's name is not text. It is a sequence of fragments, each with its own formatting, because the name can be styled. Reading it means collecting the fragments and joining them.
Take the first fragment and a database whose name has a bold word in the middle appears truncated. Take the wrong field and it is blank. Neither is an error — the request succeeded, and the result is a list of names, some of which are wrong.
Where the joined result comes out empty, a placeholder is used, so a database with an unnamed title is still selectable rather than appearing as a blank row nobody can identify. And entries with no identifier are dropped entirely, so nothing offered in a list can be chosen and then fail to resolve.
What is in place, layer by layer
How this connector is pinned
A pinned interface version
A specific date sent on every request, so the interface behaves as it did when the connector was written and an upgrade is a decision somebody makes.
Carried in a header, set once
The version travels as a term of the request rather than threaded through every address, so no call can be pinned while another is not.
A date rather than a release name
How far behind the connector is readable without knowing anything about the provider's versioning conventions.
Titles assembled from their fragments
A styled database name is read by joining its parts, so a name with formatting in it is not truncated to its first run.
A placeholder for unnamed entries
A database whose title resolves to nothing is still selectable rather than appearing as a blank row.
Unusable entries dropped
Anything without an identifier is not offered, so nothing selectable can fail to resolve afterwards.
Databases discovered rather than typed
What the integration has been given access to is fetched and offered by name, so no identifier is ever pasted.
The credential encrypted at rest
Stored on the row for one workspace, never in configuration, and never written into a log line.
What this connector can reach at all is decided by the provider's own per-page sharing rather than by a scope we request — which is its own subject and covered separately.
Three positions held on purpose
- The interface version is pinned rather than tracked. The maintenance obligation that creates is the point: the same work arrives either way, and scheduled is better than diagnosed from a symptom.
- The version is set in one place and carried on every request. A version threaded through constructed addresses is a version that will eventually be present on some calls and absent on others, with no way to notice.
- Structured values are read as structures. A styled title is a sequence of fragments, and taking the first one produces a list of names that are quietly wrong with no error anywhere.
Five questions about interface versioning
Which version do you use?
A good answer sounds like
A specific one.
What ours actually is
A pinned date sent on every request, so behaviour does not shift on a provider release.
What happens when they change something?
A good answer sounds like
Nothing, until we move.
What ours actually is
A pinned version freezes behaviour; upgrading is a decision that can be tested and undone.
How far behind are you?
A good answer sounds like
A readable answer.
What ours actually is
A date, so the answer is a span of time rather than a release number needing context.
Could some calls be unpinned?
A good answer sounds like
No.
What ours actually is
The version is set once on the client and carried on everything it sends.
What breaks if you never upgrade?
A good answer sounds like
Eventually, everything.
What ours actually is
A pinned version is retired in the end, which is why the upgrade is scheduled work rather than a surprise.
Our take
If you are designing an interface other people will build against, a dated version in a header is close to the best arrangement available. It lets you improve continuously without breaking anybody, it tells every caller exactly how far behind they are in a unit that needs no explanation, and it keeps the version out of the address where it does not belong. The reason more providers do not do it is that it requires maintaining old behaviour rather than expecting everyone to migrate — more work for them and much less for everybody else, which is what a good interface trade usually looks like.
Ask which version an integration is pinned to
An unpinned integration changes behaviour on somebody else's release schedule, and the changes that matter produce wrong data rather than errors.
Talk through contact syncingFrequently asked questions
What happens when Notion changes their API?
Nothing, until we move. The connector pins the version it was written against, sent on every request, so the interface behaves as it did then. Upgrading is a deliberate change that can be tested rather than a shift arriving on somebody else's schedule.
Why is the version a date rather than a number?
Because it describes a moment rather than a release. It lets the provider improve continuously without breaking existing callers, and it tells you how far behind you are in a unit that needs no knowledge of their conventions — two years is two years.
Could part of the integration be on a different version?
No. The version is set once when the client is built and carried on everything it sends, so there is no address somewhere with a version threaded into it that somebody forgot to update.
Does pinning mean you never update?
The opposite — it means updating is a scheduled task rather than something that happens to you. A pinned version is eventually retired by the provider, so the work arrives either way; pinning decides whether it arrives as a planned change or as a symptom to diagnose.
Our database name has formatting in it. Does that cause problems?
No. A Notion title is a sequence of formatted fragments rather than plain text, and the connector joins them rather than taking the first — which is what would truncate a name with a bold word in the middle.
