Versioning
The version is in the URL. The current version is v2.
Code
What can change in a version
Ringtime adds to a version. It does not remove from a version.
Inside v2 Ringtime can:
- Add a new endpoint.
- Add a new optional field to a request.
- Add a new field to a response.
- Add a new value to a list of values.
Inside v2 Ringtime does not:
- Remove or rename a field.
- Change the type or the meaning of a field.
- Make an optional field required.
Write a tolerant client
Your client must accept new fields. Ignore any field you do not know. Do not fail when a response has more data than you expect. This is what lets Ringtime add data without breaking you.
Breaking changes
A breaking change gets a new version prefix, for example /api/v3/. The old
version stays live. Ringtime marks it as deprecated in this documentation and in
the specification, and gives a sunset date. After the sunset date the old
version stops.
Ringtime tells each affected organization before it deprecates a version.
Which endpoints are a contract
Only the endpoints in the API reference are a public contract. Any other route of the Ringtime backend can change at any time. Do not call a route that is not in this documentation.