API versions

The base URL is https://api.sylphx.com/v1. The v1 in the path is the shape of the API, and it never changes.

The version is a date, YYYY-MM-DD, carried in the Sylphx-Version request header. A call that names a version gets the same header back with the version that answered it, so the version a response was produced under is never a guess.

curl https://api.sylphx.com/v1/whoami \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Sylphx-Version: YYYY-MM-DD"

#How a version is chosen

The version is the first one found in this order:

1. The Sylphx-Version header on the call.
2. The version pinned on the key that made the call.
3. The version pinned on the organization.

Both pins are set when the key or the organization is created, so a version is always resolved without you naming one.

#Today

There is no version stream yet. The version you request is the version you get back, and no behaviour changes by version. This page is the contract for what happens when that changes, not a list of versions to choose from.

#When a version changes

A breaking change ships as a new date. Every older version keeps working, so a call that names one keeps its behaviour. A version is removed only after 90 days with no traffic and 30 days of notice.

#Pinning a version

Pin the version on your organization when you want an upgrade to be a decision rather than an event. The TypeScript SDK takes an apiVersion option, which sends the header for you.

#Change detection

Every resource carries two fields for change detection, both in its meta:

• generation, which increases by one on every change to the resource's spec.
• etag, a strong etag for the current state of the resource, which changes on any change to the spec, the status or the metadata.

Send the etag back with a write to make the write fail rather than overwrite someone else's change; the code that comes back is ETAG_MISMATCH, on Errors.