support multiple API versions ?
behrica opened this issue · comments
Maybe we should think about something "now" to assure future compatibility with new API versions.
(while staying at same time backwards compatible on Clojure level)
Maybe nothing is needed, just to be sure.
I somehow think that Azure will come with a new API version "soon", as current is "rather incomplete"
What I mean is, that if we keep the API as it is today;
we might come into a situation when the REST API wrapped change in an incompatible way,
we cannot support both version of the REST in the same Clojure library.
One reason for this are the "function names" in namespace api
Imagine that a version v2 of OpenAI REST removes any of the functions.
The REST API defined via paths is more "flexible" then the code here.
For Azure is see it "likely" that the next version will have more functions (which is less of a problem then less functions, but a problem as well)
I think the only "reasonable way out" and be full future proof, is to give the same flexibility to the library then REST has, which means to remove the api ns, and add 2 more parameters to the params namely version and operation
A new API version will most likely mean a new major version of this library to support the new API (and only the new API) depending on what's changed.
In the case of removal of an API operation, the library will deprecate the function accordingly.
The whole point of the api namespace is to provide a meaningful Clojure wrapper over operations exposed by the API.
These named functions provide the developer with docs, code completion and a nicer experience.
What you're suggesting almost negates the need for this library completely, as the developer might just as well use Martian directly instead and gain full flexibility.
A new API version will most likely mean a new major version of this library to support the new API (and only the new API) depending on what's changed.
In the case of removal of an API operation, the library will deprecate the function accordingly.
The whole point of the
apinamespace is to provide a meaningful Clojure wrapper over operations exposed by the API. These named functions provide the developer with docs, code completion and a nicer experience.What you're suggesting almost negates the need for this library completely, as the developer might just as well use Martian directly instead and gain full flexibility.
Yes.... I do agree with this... I came as well to a similar conclusion.. Using REST directly from Clojure is nearly as simple
as it would be when following my proposal.
A new API version will most likely mean a new major version of this library to support the new API (and only the new API) depending on what's changed.
In the case of removal of an API operation, the library will deprecate the function accordingly.
"New major version" could indeed work.
(but now it support 2 REST APIs,,,, with different release cycles.)
In this light , maybe my idea of unifying the 2 APIs was not that good.
But ok, maybe we could still couple it to version, by just making a table such as,
and increase major version, if any of the 2 changes, which should not be too often...
Supported versions:
| libray version | OpenAI REST version | Azure OpenAI REST version |
|---|---|---|
| 1.x.x | v1 | 2022-12-01 |
Ok, so we can close the issue.