Mote-api.py example - API versioning


#1

I’m just updating my ‘Controller for Mote’ app to work with the new mote-api example and see that, as is fairly common, the API version is embedded in the URIs for the routes.

This means that if you are writing a client app which needs to support multiple API versions, there is no ‘nice’ way to determine the API version a particular host is running, except by starting at the latest and iterating backwards until you find one that works. Right now, there is only one version, but if that changes, it becomes cumbersome.

So for my app, I would need to first call:
/mote/api/{latest}/channel/all/state
And if that failed, then
/mote/api/{latest-1}/channel/all/status
and so on.

A simple solution to this would be to provide the version via a non-versioned endpoint such as
/mote/api/
returning something like
{mote-api-version: "v1.0"}

This would then allow clients to call that first, and then build the version specific URIs as appropriate. This is a much nicer mechanism that the iteration approach.

Any thoughts?

As an aside, while I’m talking versions, is there a reason each route defines the entire URI, or could the common base be pulled out so if it changes (such as for a version change) it only needs to be changed once?

I’m happy to submit pull requests if needed.

Cheers
R


#2

I think it is best if you open an issue on github, where it will be considered. If you want to make a PR in association then all the better.

… I’ve had no involvement in the API so can’t comment any further, I’m just concerned that at this time of the year, a logged in request in the repository is a safer way to make sure it does not get overlooked!


#3

Issue raised and pull request submitted.

Thanks.
R


#4

Hey Richard! A very useful suggestion. I’ll implement that as part of a new version 1.1, along with your suggestions for the more specific channel json returned.