A quick tour through the current PuppetDB code base will reveal that we have kind of been making up our API versioning strategy as we go along.
- We're not consistent in how we handle cases where some versions of the HTTP endpoints are best implemented by simply calling into the logic defined by other versions of the same endpoint.
- We're not consistent in how we compile queries; there are v2 query functions that call into v1 implementations and/or vice-versa, and then the situation is compounded with v3. It's very hard to look at the code and get a clear understanding of the deltas between the versions.
- We're really not consistent in how we test the different versions of the endpoints... some endpoints assume that since their implementation just calls into a different version of the same endpoint, then we don't need to duplicate all of the tests, and we can just assume that if they pass for the old version, they'll pass for the new version, etc.
This problem is going to get worse over time, and since it sounds like we are already expecting to bump the query API version again (perhaps multiple times) in the near future, it'd be wise to get this cleaned up soon.