Our versioning strategy enables developers to understand better 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. Once released, all changes will be documented in our changelog.
Versioning Strategy
Versioning for the placer API is represented by version numbers declared in the route path for our endpoints:
https://papi.placer.ai/v1/poi/{id}
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 want to take advantage of the new functionality. Any breaking change that must be rolled out mid-cycle (for security or privacy reasons) will be made to the most recent version, with appropriate communication to all developers.
Breaking Changes
These changes require developers to change their code to maintain the 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
Non-breaking changes
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
Deprecation and retirement
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.