Following is our versioning strategy that enables developers to better understand when to expect changes to Placer's public APIs.
Developers will be notified of additions, changes, deprecations and retirements to the Placer API via email announcements, so they can appropriately plan to accommodate these changes in their development roadmap. All changes will be documented in our changelog once released .
Versioning for the placer API is represented by version numbers declared in the route path for our endpoints:
A breaking change requires developers to change their code to maintain existing functionality in their app. Non-breaking changes will be additive and rolled out to the most recent version along with the upcoming release, requiring no work on a developer’s end unless you would like to take advantage of the new functionality.
If a breaking change must be rolled out mid-cycle (for security or privacy reasons), this change will be made to the most recent version, with appropriate communication to all developers.
These changes require developers to change their code to maintain existing functionality of their application.
- Addition of a new required parameter
- Removal of an existing endpoint
- Removal of any field in the response
- Removal of a query parameter (optional or mandatory)
- Restructuring of the input or output format (e.g. objects hierarchy changes)
- Changing the name or data type of an existing input parameter or output value
- Changing the resource name
- Changing a response code
- Changing error types
This changes requiring no work on the developer’s end unless you would like to take advantage of the new functionality.
- Addition of a new endpoint
- Addition of a new optional parameter
- Addition of a new response field
- Changing text in error messages
- Availability of new scopes
- Setting fields to Null as an alternative to removing it altogether
What deprecation and retirement mean to the Placer API:
Deprecated: Can refer to field or endpoint. No new functionality will be released around that field/endpoint. Support will keep checking/fixing bugs.
Retired: The feature will no longer be accessible.
In most cases, as soon as a new version is released, the previous version will be marked as deprecated. Versions will remain in a deprecated state for a period of time, after which they will be retired.