Please Prioritize Web API Signature Compatibility Within Major Versions

rmartin16 commented 3 years ago

qBittorrent version and Operating System

v4.1+

If on linux, libtorrent-rasterbar and Qt version

n/a

What is the problem

I have a growing concern about the API incompatibilities among the v2.* minor versions. Twice recently, API signatures have changed in a minor version: once for torrents/add in v4.3.2 and again for torrents/rename_file in v4.3.3.

This makes it difficult for users to write code that is agnostic to minor versions of qBittorrent Web API. For instance, I maintain qbittorrent-api for Python.....I do not know which version of qBittorrent users will have but I want the library to work for any version without the users needing the understand the ends and outs of this API like I do. So, I am having to put all this logic to upgrade and downgrade API signatures based on the Web API minor version. I guess that's fine for me....I can take this on for the users of my library.....but I don't see how this scales as more community tools use this API.

Many people implement these APIs as one-offs in their code. See VueTorrent as an example; root_folder is being set the javascript (or whatever that is) but that's gonna break with 4.3.4....so, someone will then need to manually implement the upgrade/download of the params.

These changes will lead to community tools being stale and broken unless users stay back on old versions or devs stay really on top of every release....however, offloading the creation of such a compatibility layer to every dev using this API is almost certainly not appropriate...

What is the expected behavior

Within major versions of the Web API, please preserve API compatibility.

If these signature changes were perhaps unintentional or something....no problem, then; we can all move forward without further breaks.

Thanks.

glassez commented 3 years ago

In fact, we simply can't pay enough attention to web API problems due to the lack of active developers. We mostly just care about the built-in web interface. Maybe the feedback from API users will help clarify how we could do this better. Often, these changes are related to changes in the core of the application, so we just follow them. It seems that in order not to break the existing web API, we could do something from the following:

Keep backward compatible API for changed features. In this case, some new functionality may not be available through the API.
Keep existing API for removed features but make it "does nothing" stubs. I'm not sure that this will bring much benefit to web API users.

glassez commented 3 years ago

I have a growing concern about the API incompatibilities among the v2.* minor versions. Twice recently, API signatures have changed in a minor version

BTW, we use the minor (second digit) versions of the API to indicate such incompatible changes. The major version is reserved for conceptual changes to the API (i.e., for a total redesign).

rmartin16 commented 3 years ago

I think this is all mostly about balance...since nothing is without trade-offs. Any attempt to maintain compatibility will only create more work for code maintenance; alternatively, the work doesn't really goes away if compatibility isn't maintained....other people in the community will just have do it. I can sympathize, though, with already having more work than people to do it.

As for actual approaches to compatibility, I think we can consider in more depth the two examples I brought up.

In torrents/add, root_folder was replaced with the more robust content_layout.

For compatibility, the root_folder parameter could continue being supported by simply setting content_layout appropriately within the API before calling into more core functionality.

In torrents/rename_file, the file_id param was replaced with the more robust old_path and new_path.

Similarly for compatibility, the API could make an attempt to determine the old_path and new_path from the file_id.
This is probably more onerous then converting root_folder -> content_layout....but doesn't seem impossible...

This approach:

would be a small but certainly non-zero introduction of tech debt that I think is reasonable when updating the API.
would allow community code that worked in the recent past to continue working for later versions...to a certain point anyway.

This second point is the primary advantage in my mind. As this API is used more and more, maintaining this type of compatibility allows for the core application to move forward while this exposed API remains more stable for existing code.

There is a lot of room for decision making here....going back to the trade-offs. But I think the best move forward is to default to preserving compatibility unless it clearly isn't worth it...this is clearly subjective among the devs.

These are just my thoughts, though, as a advocate for qBittorrent and its API. I don't know all/any of this team's priorities....but I, at least, wanted to express there is some desire for API compatibility in the community.

Thanks.

rmartin16 commented 3 years ago

There is also a completely different approach where compatibility isn't a problem at all. Let the (external) calling code determine which version of the API to invoke. That way, any application can continue using v2.7 and they don't have to concern tehmselves with what was introduced in v2.8.....although, I don't think the current architecture of the API will allow something like this. Just thinking.

qbittorrent / qBittorrent