API reference and APIClient docs could be improved

[DavidSonoda]

Hi,

I've been writing some simple utilities with clearml and found some inconsistencies between the Server API reference and the APIClient provided by the python SDK. Although the Server API Reference is documenting the HTTP APIs, not all APIs are available from the APIClient. However, in the APIClient section of the documentation, it does not mention about supported API endpoints. This creates confusions. For example:

I needed to fetch the queues and their connected workers using the APIClient, then I found this API:

queues.get_all_ex()

However, calling this from the python SDK will throw the following error:

AttributeError: 'Queues' object has no attribute 'get_all_ex'

I've checked the source code, seems like the queues.get_all_ex() is not implemented yet. I think mentioning this in the APIClient/Server API reference documentation would greatly improve the clarity of the docs and reduce confusion.

To do that, I got some thoughts:

• Adding an API version selection for API reference docs, possibly by adding a dropdown menu?
• Then for each version of the Server API, corresponding clearml SDK versions could be listed, whose APIClient will support the version of the Server API.

Forgive me If my suggestion will break the current implementation of the docs, as I noticed the API references are auto generated according to the code. So my thoughts are by no means the best since I have no idea how much work is needed to do that.

Thanks.

[ainoam]

Thanks for pointing this out @DavidSonoda.

*_ex APIs are intended for use by ClearML's UI implementation - They are considered a volatile interface with no guarantee for functional specification or backwards compatibility, and as such their use is discouraged.

Adding an API version selection for API reference docs, possibly by adding a dropdown menu?

Though having no direct impact on APIClient (which is a client side release), this is a great idea which is indeed on our todo list.
For the time being, the published documentation refers to the latest server release. If you are running an older version - You can reference the in-code docstrings of your version.

Then for each version of the Server API, corresponding clearml SDK versions could be listed, whose APIClient will support the version of the Server API

The APIClient is intended for automation of tasks that the python package handles, and as such the endpoints implemented would be ones for APIs used by that package (Notice it is provided as part of clearml/clearml-agent, and not the server repo - It makes no guarantee to encompass the entire backend API).

The ClearML Server is fully backwards compatible, so it will support any version of APIClient (Which, naturally, will implement APIs of the server version available at the time of its release).

That said, we can certainly look into clarifying which APIs are supported by an APIClient implementation.

[DavidSonoda]

Thank you so much for the reply.

*_ex APIs are intended for use by ClearML's UI implementation - They are considered a volatile interface with no guarantee for functional specification or backwards compatibility, and as such their use is discouraged.

The reason why I used *_ex api, especially for the queues module, was to fetch the related worker information of queues, which wasn't provided by the normal version of the api. That being said, pointing this general rule of discouraging the use of *_ex api in the docs could possibly help.

However, generally speaking I think the APIs are really well designed and straight forward to use. Thanks for all the work.