Versioning and Stability
Every call in the reference carries one of two marks.
| Mark | Promise |
|---|---|
| Preview | Ready to use. Its parameters, fields and behavior may still change, and each change is listed in the changelog. |
| Stable | Backward compatible. It changes only by addition: new optional parameters, new fields in a response, new values in a list of allowed values. |
Every API call is in Preview right now while we gather feedback. We expect few breaking changes. As calls settle they move to Stable, and the changelog records each move.
The API has no version number in its address or its headers. A change that would break a Stable call would need a version header that your client chooses to send. A client that does not send the header sees no change.
Best practices for API compatibility
Additions can arrive at any time, on Preview and Stable calls alike. An API client that follows these rules will continue working even as our API evolves:
- Ignore fields you do not know. A response can gain fields.
- Expect new values. A field with a list of allowed values can gain one.
- Do not depend on the order of fields in a JSON object.
- Treat an
error_codeyou do not know as its HTTP status. New codes can be added. - Act on
error_codeand the HTTP status. Do not act on the wording oferror, or ofmessageat the top level of a response: both are written for people and can change. A status field inside an object, such as an agent'sagent_status, is a set of named values you can act on. - Treat ids and cursors as opaque strings. Do not parse them or assume a length.
What you send is checked just as strictly: a parameter or body field the call does not take returns 400. A misspelled name is reported at once.