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.