Stability of the Payroll Integrations API is a top priority for the team. Therefore, maintaining backward compatibility and avoiding breaking changes is critical. This page outlines what is and is not considered a breaking change, and what may be rolled out without a new API version or advance notice.
To be notified of new API functionality and to be contacted in the rare case of API deprecation, contact success@payrollintegrations.com to be added to our mailing list.
Non-Breaking Changes
Additive Changes
Additive changes include updates to API functionality without introducing regressions or changes to existing behavior.
- New functionality will continue to be introduced through new endpoints, but existing implementations will not be affected.
- New optional parameters or fields may be added to API requests and responses. API endpoint behavior will remain unchanged when these optional fields are not used. (Example: an optional sort parameter added to an endpoint that returns a list)
- Error messages or codes may be added to improve error documentation and debugging.
- More enum values may be added to existing fields or properties.
Ensure your implementation can handle unknown enum values with a strong
default case.
Documentation Changes
- Updates to match underlying non-breaking implementation changes
- Improvements to examples, descriptions, or guides with more detail
- Corrections to spelling, grammatical, organization, or other minor adjustments
General Improvements
- Fixes for behavior that does not match what has been documented.
- Optimization improvements are frequently made, and will never impact client implementations.
- Infrastructure upgrades may be done to improve performance or offer new functionality, but if it does not impact client implementations, it will be done without advance notice.
Breaking Changes
Breaking changes are avoided whenever possible. If deemed unavoidable, the new functionality will be offered under an incremented version, and the prior version will be marked as deprecated. The deprecation period will vary on a case-by-case basis, and the changes will be proactively communicated to clients who are utilizing the deprecated version to assist in building a migration plan.
Examples of breaking changes
- A request parameter becoming mandatory
- Infrastructure changes that require updating the API’s base route
Robust Implementation Recommendations
- Use a tolerant JSON parser that does not rely on exact ordering of fields and can ignore unknown fields
- Handle unknown enum values with a strong default case. Fields with documented enum values will also include a recommended default case.
