RUNNING

How the API changes

What you can rely on while you write a script against it.

What is published

The API is made of services, and each is one of three things.

Tier	What it means	Notice before a published call changes or goes
Stable	Built to be depended on.	At least 12 months
Beta	Complete enough to use, still settling.	At least 90 days
Internal	Everything not listed. Not documented, not in the OpenAPI document, and nothing about its shape is promised.	None

Today RunService is beta. The reference lists what is published.

The tiers differ in the notice promised, not in what our compatibility check holds: it treats every published call alike, including a call marked Not released yet.

Inside a version, changes only add

Within runninglake.v1 a published service changes by adding.

A new call, a new optional field, a new value of an enumeration and a new error reason may appear at any time.
A field is never removed, renumbered, retyped or renamed, and that includes its JSON name. A call is never removed or moved. A field never changes from one value to a list. A value of an enumeration is never removed.

So write your client to tolerate what the server may add without notice.

An enumeration word it does not know: treat it as something newer than the client, not as an error.
An error reason it does not know in rl-error-reason: fall back on the Connect code.
A field it does not know in a JSON response: ignore it.

Notice before something goes

A published call that will go is deprecated first, with notice at least as long as its tier promises: 12 months for stable, 90 days for beta. Each response to a deprecated call carries two headers: Deprecation, the day the notice was given, and Sunset, the first day the call may stop working.

No call is deprecated today, so no response carries either header yet.

A request the server cannot decode, or a method it does not allow, is refused before the headers are added, and carries neither.

A break is a new version

A change that cannot be made by adding is made in runninglake.v2, which is served beside v1 for at least 12 months. v1 does not change under you while you move.

Rules every call keeps

Lists page one way. A call named List… takes pageSize and pageToken and answers nextPageToken. A page is at most 200. A token is opaque, and is refused as invalid_page_token if the filters change between pages.
Calls that make something take an idempotency key. A call named Create…, Start… or Rotate… takes an idempotencyKey of 1 to 128 characters. The key is scoped to the caller, not the organisation: two teams sending nightly make two things, and one caller retrying gets the first one back, with replayed set.
A read that writes nothing may be a GET. A call named Get… or List… that records nothing may be sent as a GET. A call that takes a claim or a secret is never a GET, because a GET puts the request in a URL.

The names are part of the promise: these rules find a call that makes something, or one that only reads, by its name.