Versioning & compatibility
The Listo Public API uses two parallel version markers and one compatibility rule that governs both.
Where the version lives
| Surface | Where the version appears | v1 value |
|---|---|---|
| REST API | URL prefix | /v1/tenants/{tenantId}/screenings |
| CloudEvents | type suffix | com.auditdata.listo.screening.completed.v1 |
A new major version is published as a new URL prefix (/v2) and a
new type suffix (...completed.v2). The two move together.
Additive evolution within a major version
Within a single major version, we may add new optional fields to
the REST response body and to the CloudEvent data payload without
bumping the version. We will not change the meaning, type, nullability,
or required-ness of any existing field within the same major version.
| Change | Version bump? |
|---|---|
Add a new optional field on REST or data | no |
Add a new event type (a brand-new event) | no — it ships as its own type |
| Add a new endpoint | no |
| Rename, remove, or retype an existing field | yes |
| Change the meaning, range, or nullability of an existing field | yes |
| Add a new value to an existing enum field | yes |
| Make an optional field required (or vice versa) | yes |
Consumer contract
Your consumer must tolerate unknown fields. A future release may add fields that didn't exist when you wrote your handler, and your code must not throw, log-spam, or drop the event when that happens.