Paychex APIs use versioning to manage change over time. Paychex APIs follow the general principle to version only when necessary, based on structural changes in the representation of a resource. API changes are not typically driven by feature releases but by a “breaking” change.
A "breaking" change is defined as structural change in a resource representation that would break code previously written based on the current representation. When this occurs, we will release a new vendor media type to describe a breaking change associated with a resource. This vender media type will have a new Major version that captures the breaking change of the resource being presented. If changes cannot be overcome using this approach the impacted consumers will be notified.
You should anticipate that Paychex will extend our APIs, in a non-breaking manner, as we add features to our offering. We extend APIs using the following approach:
We will never drop arguments or fields
We will not change the meaning of the resource representation or state
When we add arguments or fields, they will be optional with appropriate defaults set when necessary
Using hypermedia controls, the vendor media type that you should use to transition between states is provided as part of the links you receive. Thus, as a consumer you will always know the version(s) of the resource states to which you can navigate.