Enhancement: Allow Users to Specify API Version of URL Endpoint to Query

[mabilton]

Fixes #55.

Description

Major changes:

• Added url_version attribute to koordinates.Client; this allows the user to explicitly specify the API version of the URL endpoint they'd like to query.
• Added api_version attribute to koordinates.Client, which specifies the version of the Koordinates API that should be assumed to work out request/response structures. This can differ from the url_version (e.g. api_version='v1' vs url_version=v1.x).
• Removed URL_TEMPLATES__v1 in favour of a _get_url_templates helper method. This prints more understandable error messages in cases where the user requests an invalid api_version. This change should also make it easier to accommodate new koordinates API versions in the future.
• Added new tests for url_version attribute.
• Modified test fixtures that explicitly referenced URL_TEMPLATES__v1.

Miscellaneous changes:

• Bumped black version in .pre-commit-config.yaml to 24.8.0 to avoid issues with click; see Incompatible with click 8.1.0 (ImportError: cannot import name '_unicodefun' from 'click') psf/black#2964.
• Removed rogue print statement in tests.

Example:

import koordinates

host = "data.linz.govt.nz"
linz_api_key = '123'
client = koordinates.Client(host="data.linz.govt.nz", token='123', url_version='v1.x')
print(client.get_url("PUBLISH", "DELETE", "single", {"id": 'abc'}))

This prints: https://data.linz.govt.nz/services/api/v1.x/publish/abc/.

Any feedback/suggestions are welcome.

Cheers,
Matt.

[benpearman]

Hi Matt, thanks for your PR.

I'm unclear why url_version and api_version are both necessary. Can you give me an example situation where one needs to differ from the other? I think api_version by itself should be sufficient

[mabilton]

Hey @benpearman. I outline the rationale for this change in #55. For my own understanding, would you be able to give a brief explanation as to why the LINZ's Koordinates site would use 'v1.x' as its endpoint (at least temporarily) instead of 'v1'? If its for maintenance/update purposes, perhaps there should be some kind of 'catch' in the koordinates package that checks for this if its unable to reach the 'v1' endpoint? Thanks in advance for your help.

[benpearman]

The v1 API is stable and won't have breaking changes. That is why the Python plugin here uses it.

Whereas the v1.x API includes frequent changes which might break plugins that depend on it. If you use the v1.x API with the plugin as is, some of the functionality may not work.

I am not sure what happened with the maintenance you reference in that issue, but LINZ's Koordinates site normally uses the v1.x API, rather than the v1 API.

[mabilton]

Hey @benpearman - thanks for that clarification. Just a couple of follow-up points/questions from me:

1. When I go onto https://data.linz.govt.nz/ to export some data, I see that it's still firing off post requests to https://data.linz.govt.nz/services/api/v1.x/exports/ (see screenshot). Is this expected?
   
2. Are there any circumstances under which the user would want to query the 'v1.x' endpoint instead of the 'v1' one?

[benpearman]

1. Yes those requests looks normal and expected.
2. There are some specific export options that are not accessible on the v1 exports API. But in general, v1 is recommended since it is stable and sufficient for most use cases.

Hope that helps!