Our philosophy is to try and avoid creating new versions as much as possible. Any changes to an APIs payload, either in creation or in responses, should be as backwards compatible as possible. We do not consider adding new endpoints to be “breaking changes”, so would not consider releasing a new version. Always achieving backwards compatibility however is often an unrealistic expectation for the long term, any self-respecting API will need to offer some kind of a solution. Our approach is to version API endpoints by service and in the request URL’s path. This implies that if we only need to make changes to a single service, all the other services are isolated. It’s easier to log or debug requests and extract statistics from logging data. You’ll see in the documentation that each service’s end-points include the version in the URL path, a few examples:
  • GET https://api.invopop.com/utils/v1/ping
  • PUT https://api.invopop.com/transform/v1/jobs/XXXXXX
  • GET https://api.invopop.com/silo/v1/envelopes
If at some point in the future for example we decide to refactor our transform job creation service, we’ll be able to suggest clients switch from transform/v1 to transform/v2 as part of their migration process.