Zuplo API v4
Contract and Lifecycle

Versioning and Lifecycle

/v4 is the version of all of Zuplo's API, not of one subsystem. Stable v4 surfaces only change additively: anything that would break a client is added next to the old surface instead.

One version for the whole API

The shared rule VER-1 versions per subsystem. That is exactly how customers ended up with monetization v1, v2 and v3 next to API keys v1. v4 deliberately departs from it: one prefix, one set of conventions, one OpenAPI document. New capabilities are added to v4.

Do
One prefix for every product
Code
/v4/buckets/{bucketId}/ai/pools
/v4/buckets/{bucketId}/consumers
/v4/accounts/{accountId}/buckets
Don't
A version per subsystem
Code
/v3/metering
/v2/key-auth
/v1/api-keys

Changing v4 without breaking it

VER-3

Within v4, only additive changes are allowed. A breaking change to a stable v4 surface is not made: a replacement is added next to it, and the old one goes through deprecation.

Review
Allowed
Non-breaking
  • new operations and collections
  • new optional request fields and parameters
  • new response fields
  • new enum values (enums are extensible)
  • null where there was none
Not allowed
Breaking
  • removing or renaming a path, field or parameter
  • new required request fields, or making an optional field required
  • changing a field's type or format
  • removing an enum value, or accepting fewer request values
  • changing a status code or error type

Maturity labels

VER-4

x-stability: preview or x-stability: beta marks surface that may still change without a deprecation period. No label means stable.

Lintv4-document
Today
x-stability: preview

The whole v4 document. It may still change without a deprecation period.

Graduation
Remove the label

Operations graduate individually.

Stable
No label

Bound by the table above from then on.

Do
Stability in the spec
YAMLCode
x-stability: preview
Don't
Stability in the URL
Code
/v4beta/buckets/{bucketId}/ai/apps
/v4/buckets/{bucketId}/ai/apps-preview

Deprecation

VER-2

A deprecated operation is marked and announced, gets at least 90 days of notice when it is stable, and is removed only after its sunset date. Unchanged from the shared rule.

Review
1. Mark it
deprecated: true

Plus a successor in the description.

2. Announce it
Deprecation and Sunset headers

At runtime, from the http-deprecation-outbound policy.

3. Wait
At least 90 days

Of notice, for stable operations.

4. Remove it
410

410 Gone after the sunset date.

v1 to v3 and api.zuplo.com

Frozen

Existing dev.zuplo.com versions are frozen and keep working.

Moved resource by resource

The portal moves to v4 resource by resource. A portal feature built on v4 no longer needs its api.zuplo.com counterpart.

Removed when unused

When nothing calls an api.zuplo.com route anymore, it is removed.

Lint
Fails CI on any finding
v4-path-shapev4-document

One /v4 prefix on every path (VER-1), and x-stability on the document (VER-4).

Review
Checked by people in the pull request

Breaking changes (VER-3) and deprecations (VER-2).

Every rule ID and what enforces it: the rule index
Last modified on
Writing the OpenAPI SpecRule Index