Add support for using ZULIP_FEATURE_LEVEL to determine how to encode parameters

zulip / python-zulip-api

Python library for the Zulip API.

https://zulip.com/api/

Apache License 2.0

350 stars 352 forks source link

Add support for using ZULIP_FEATURE_LEVEL to determine how to encode parameters #683

Open timabbott opened 3 years ago

timabbott commented 3 years ago

As part of https://github.com/zulip/zulip/issues/18035

We should implement this as follows:

A commit should make a Client object do a GET /server_settings and store the feature_level and server version as properties.
We can then write functions to encode parameters differently depending on the feature level. for update_user as a sample case, in preparation for the API migration there.
We can figure out a test suite strategy to ensure that these actually work across versions. E.g. maybe we have CI to run the zulip/zulip tools/test-api tests for 2.1, 3.0, 4.0, and master against the Python bindings.
Once we've figured out the infrastructure for this, we can make a master issue to make everything in our API changelog be supported across versions by this project.

@ligmitz FYI.

timabbott commented 3 years ago

Also @msurfer @orientor @LoopThrough-i-j FYI, since if we implement this correctly, it would adjust and hopefully improve the workflow for making API changes.

LoopThrough-i-j commented 3 years ago

Exactly something I was looking for and couldn't find. This could create a door for writing integration tests for the API clients and much more.

timabbott commented 3 years ago

@PIG208 FYI as well; this is probably one of the more important features for us to add to the Python API bindings.

@neiljp also FYI, since this may have some utility for ZulipTerminal as well (if you can transparently handle some API upgrades).

neiljp commented 3 years ago

We already fetch the feature-level and adjust some behavior based on it. It's not clear to me precisely what's involved here, but we can likely handle this via a zulip dependency upgrade or via feature-level conditionals?

Is this required (ie a ZT bug as of now) or optional (ie. ZT api migration, or subject->topic)?

timabbott commented 3 years ago

The goal as stated here is just to have things written with the python-zulip-api transparently handle how to call endpoints (E.g. if we rename an endpoint or we change how a parameter to send is encoded). I think ZT will still need to have all the logic for parsing event formats, etc., though it would certainly be reasonable to consider as a follow-up having a shared function here that converts any old-format events into newer-format events.

Relatedly, we probably want python-zulip-api to pass various client_capabilities by default? Not sure.

timabbott commented 2 years ago

@PIG208 I think this is probably the most important issue for the Python bindings. I think in particular we want to pass all the client_capabilities currently documented by default, to encourage coding against the latest API when writing new clients.