Paychex APIs use versioning to manage change over time. Paychex APIs generally following these general principals
- We don't do it - its an anti-pattern.
- We will version only if we absolutely must.
- When we do version, the media type and profile are used to specify the version of the resource representation being transferred.
API changes are not driven by feature releases but rather based on structural changes in the representation of a resource. A "breaking" change is defined as structural change in a resource representation that would break code that was previously written based on the current representation. When this occurs we will release a new profile to describe a breaking change associated with a resource. This profile will have a new "major" version that captures the breaking change of the resource being presented.
No versioning does not mean no changes. 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 media type and profiles 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.