Continuous release
The Dotfile API is deployed continuously, with zero downtime. There is no maintenance window to plan around and no release to schedule an integration against.
Every change that reaches production is published in the API changelog. That page is the record of what changed and when.
Breaking changes are announced ahead of the release, and are rare: backwards compatibility is the default. When one is unavoidable, the announcement precedes the release by at least one month, a backwards-compatible path and a deprecation notice ship first, and reminders follow until the release.
API versioning
The Dotfile API uses major-release versioning: v1, v2, v3, and so on. Only v1 exists today, and every change is bundled into it. Incremental changes are logged in the API changelog.
A change is either breaking or non-breaking, and the distinction determines how it is released.
Breaking changes
A breaking change is one that is not backwards compatible with the previous state of the API and causes existing integrations to fail or behave unexpectedly. If an integration that worked before the change has to be updated to keep working, the change is breaking.
Before a breaking change ships, the property or endpoint it affects is marked deprecated in the OpenAPI specification and in this reference, and its description names the replacement to migrate to. For example, template_id on the case object is deprecated in favour of template.key, and assignee_id in favour of assignee.id. A deprecated field keeps working until the breaking change is released.
Non-breaking changes
A non-breaking change is backwards compatible with the previous state of the API. Additive changes are generally backwards compatible and ship without advance notice.
An additive change can still alter behaviour in ways an integration did not anticipate. An integration that generates a validation schema from the OpenAPI specification and rejects unknown fields will see errors on changes classified here as non-breaking. Tolerate unknown properties and unknown enum values when parsing responses.
Classification
| Modification | Classification |
|---|---|
| Removing an existing API endpoint | Breaking |
| Removing, renaming, or changing the type of an existing property | Breaking |
| Making an existing optional property required on a request body schema | Breaking |
| Making an existing non-nullable property nullable on a response body schema | Breaking |
| Removing or renaming a possible value of an existing enum | Breaking |
| Removing an existing webhook event | Breaking |
| Changing the authentication method or security protocols | Breaking |
| Decreasing a rate limit | Breaking |
| Making a validation constraint stricter, such as lowering a maximum length | Breaking |
| Adding a new API endpoint | Non-breaking |
| Adding a new optional property on a request body schema | Non-breaking |
| Adding a new optional query parameter | Non-breaking |
| Adding a new value to an existing enum | Non-breaking |
| Making an existing optional property required on a response schema | Non-breaking |
| Making an existing nullable property non-nullable on a response schema | Non-breaking |
| Making a validation constraint less strict, such as raising a maximum length | Non-breaking |
| Adding a deprecation notice on an existing endpoint or property | Non-breaking |
| Updating documentation, or the description of an endpoint or property | Non-breaking |