Data Versions
Versioning data prevents unintended changes when performing updates.
Scenario
Ghee's hard work has paid off in the form of a big promotion and raise. Congrats Ghee! An application makes the update to Ghee's pay rate.
At his new income level, Ghee immediately jumps on a nicer apartment he's had his eye on. A short time later, another application sends a patch request to reflect the change of address in Ghee's account. Nice!
Unfortunately, the patch was sent in a request body that still had the old pay rate, effectively demoting Ghee. Payroll is ran after the address change/pay rate reversal, and Ghee's direct deposit comes in woefully short for his new rent. Whoops.
Needless to say, Ghee is kicked out of his new apartment and is reduced to walking back to his parents' house in the rain and catches pneumonia.
Versions
The version of a data object represents the state of that object. If an object patch request is sent without the correct (latest) version, the request will be rejected with a version mismatch. The object will need to be pulled again to obtain the latest information and version to be included with the new patch request.
Requiring the version ensures that a user has an accurate data object to update against and prevents unintentional consequences resulting from using an old data object.
API Versions
API versioning ensures an existing partner application doesn't break when changes need to be made to the API.
Versioning in the OnPay API is achieved in the url, e.g. https://onpay.dev/:version/example. When building an application against a specific version of the API, partners can feel confident that the behavior of that version will not change as long as that version is supported. Changes that would break an existing version utilization will be applied to a new version. This means that employee patch you wrote way back against v1 will continue to work after versions 2 & 3 are released.