Unable to Connect to Koordinates Websites where API Version in URL is not 'v1'

[mabilton]

Description

koordinates is unable to connect to Koordinates websites where the API version in the URL endpoint is not 'v1'.

For example, as of ~7 pm 16 Aug 2024 NZT, it appears that the Land Information New Zealand (LINZ) Koordinate site was undergoing some kind of maintenance which meant that the API endpoint https://data.linz.govt.nz/services/api/v1/layers/ was not responding, but the https://data.linz.govt.nz/services/api/v1.x/layers/ endpoint was. As of 12:20 pm 17 Aug 2024 NZT, it appears that LINZ has since fixed this issue.

Interestingly, inspecting the network traffic on the LINZ Koordinate site when performing an export shows that it queries the 'v1.x' endpoint rather than the 'v1' endpoint, even when both endpoints are seemingly functioning.

Minimum Working Example

import koordinates

host = "data.linz.govt.nz"
linz_api_key = 'YOUR LINZ API KEY HERE'
client = koordinates.Client(host=host, token=linz_api_key)

for layer in client.layers.list()[:10]:
   print(layer)

Error trace:

Traceback (most recent call last):
  File "/home/mabilton/Public/Programming/python-client/temp.py", line 7, in <module>
    for layer in client.layers.list()[:10]:
  File "/home/mabilton/Public/Programming/python-client/koordinates/base.py", line 265, in __getitem__
    return list(itertools.islice(self.__iter__(), k.stop))
  File "/home/mabilton/Public/Programming/python-client/koordinates/base.py", line 203, in __iter__
    r = self._request(url)
  File "/home/mabilton/Public/Programming/python-client/koordinates/base.py", line 147, in _request
    r = self._manager.client.request(method, url, headers=self._to_headers())
  File "/home/mabilton/Public/Programming/python-client/koordinates/client.py", line 169, in request
    r = self._raw_request(method, url, headers, *args, **kwargs)
  File "/home/mabilton/Public/Programming/python-client/koordinates/client.py", line 215, in _raw_request
    raise exceptions.ServerError.from_requests_error(e)
koordinates.exceptions.NotFound: 404 Client Error: Not Found for url: https://data.linz.govt.nz/services/api/v1/layers/

koordinates version: 0.7.2
python version: 3.10.12
Run on: 16/08/2024, ~7pm NZT. Note that the above code snippet works as of 12:20 Aug 17 2024 NZT.

Suggested Fix

It seems that the general issue here is that the koordinates library currently assumes that the API version listed in the API URL is always the same as API version, which evidently isn't true all of the time (e.g. 'v1' vs 'v1.x').

I propose two minor fixes to address this issue:

1. Add a url_version attribute to the koordinates.Client class, which specifies the API version to use in the URL to query.
2. For the sake of 'future proofing', add an api_version attribute to the koordinates.Client class and remove all hard-coded references to 'v1' in the codebase.

I've been working on a PR which addresses these issues, which I will link shortly.

Cheers,
Matt.