Skip to main content
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. Complete backward compatibility over the long term is unrealistic. Every serious API must offer a mechanism to deal with breaking changes. 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.