Versioning
/v1 only ever grows. Anything breaking waits for /v2, and /v1 keeps working for 12 months after that.
The version is in the path: https://api.whocoming.com/v1/.... There is no date header to pin and no per-account version to upgrade.
What we promise for /v1
We may add:
- new endpoints,
- new optional request fields and query parameters,
- new fields in responses,
- new values in a list of event types or error codes,
- new webhook event types, which are only sent to endpoints that subscribe to them,
- new values in the response fields marked
x-open-enumin the OpenAPI document and "New values may be added" in the reference: an RSVP'ssource, a question'stype, a public event'sstate, a delivery'sstatus, a usageplanand webhook event types, - higher limits: a longer maximum, more items, a wider range.
Every other value list in a response (such as an RSVP's status, an event's status and visibility, and mode) is closed: a new value there would be a breaking change and waits for /v2.
We will never, within /v1:
- remove or rename an endpoint, a field or a parameter,
- change a field's type,
- make validation stricter (a request that works today keeps working): no new required field or parameter, no lower maximum, no new pattern or format, no value dropped from a list,
- make a response field that is always there optional, or let it hold a new type (including
null), - change what an error code means.
A test in our build checks this promise on every change, not just intends it. It records every endpoint, parameter, status code, field, type, format, value list, pattern, length and range limit and required list of the published API, and fails on any change that would remove, rename, retype or tighten one of them.
What that asks of you
- Ignore response fields you do not know.
- Do not fail on an error
codeor webhooktypeyou do not know; treat it by its HTTP status. - Do not fail on a new value in an open list (see above): show it as-is or fall back to a default.
- Store IDs as opaque strings; their length may vary.
When /v2 comes
Anything breaking waits for /v2. When it ships, /v1 keeps working, unchanged, for at least 12 months alongside it, so you can move over when it suits you.
The embed
https://cdn.whocoming.com/embed.js follows the same rule: the element's tag, attributes, CSS variables, ::part() names, DOM events and strings keys are only ever added to.
What changed and when is in the changelog.