[Freeipa-devel] Designing better API compatibility

[Petr Vobornik]

On 04/09/2015 09:35 AM, Martin Kosek wrote:
> On 04/09/2015 09:16 AM, Jan Cholasta wrote:
>> Dne 8.4.2015 v 16:44 Martin Kosek napsal(a):
>>> On 03/20/2015 05:00 PM, Petr Vobornik wrote:
>>>> On 03/20/2015 04:16 PM, Petr Spacek wrote:
>>>>> On 20.3.2015 15:51, Nathaniel McCallum wrote:
>>>>>> On Fri, 2015-03-20 at 09:58 -0400, Simo Sorce wrote:
>>>>>>> On Fri, 2015-03-20 at 14:38 +0100, Martin Kosek wrote:
>>>>>>>>
>>>>>>>> Correct. I see 2 approaches here:
>>>>>>>>
>>>>>>>> a) Thin client, which simply downloads metadata from the (old)
>>>>>>>> server and won't
>>>>>>>> use unsupported commands/parameters
>>>>>>>> b) Not-so-thin client that knows the minimal API versions of
>>>>>>>> commands/parameters (can be annotated in the code), that would
>>>>>>>> ping the server
>>>>>>>> first to identify it's version, validate that the chosen set of
>>>>>>>> commands/parameters is supported on that server and then send the
>>>>>>>> commands with
>>>>>>>> that version.
>>>>>>>
>>>>>>> If we have a recognizable error the client can take an optimistic
>>>>>>> approach, send the command normally, if it gets an error that the
>>>>>>> server does not understand it, it checks the version in the reply
>>>>>>> and falls back to an older "baseline" version of the command (if
>>>>>>> possible) or bails out with an error.
>>>>>>
>>>>>> My understanding was that:
>>>>>>
>>>>>> 1. We already publish all the information necessary to implement a
>>>>>> thin client, and have for some time.
>>>>> We certainly have *some* data but real thin client will most likely require
>>>>> some changes. Some information like return types and so on are missing.
>>>>>
>>>>>> 2. Thus, the thin client would work on both new and old versions since
>>>>>> it just simply translates from user input into JSON/XML.
>>>>>>
>>>>>> 3. Only plugins with specific client behavior would need to be ported
>>>>>> to the thin client. A prime example of this is otptoken-add-yubikey.
>>>>>>
>>>>>> My preference is solidly for implementing the thin client first. Once
>>>>>> we have decoupled the client from the current plugin framework, server-
>>>>>> side changes can be made in isolation. This decoupling is the move
>>>>>> that is essentially necessary to provide proper API versioning. And if
>>>>>> this can't land for 4.2, land it in the next release. I'd rather do
>>>>>> API-stability correctly and a release later than rushed with
>>>>>> compromises. We have to live with this forever.
>>>>> + all votes I have :-)
>>>>>
>>>>
>>>> +1
>>>
>>> Ok. So to sum up this thread (and do the actual changes in Trac), in FreeIPA
>>> 4.2, we would:
>>>
>>> 1) Prepare the API UI browser or generated API documentation so that people
>>> could finally see the existing API without having to read the code or inspect
>>> jquery sent by the Web UI.
>>>
>>> https://fedorahosted.org/freeipa/ticket/3129
>>
>> This is not related to API compatibility, it just uses the same metadata.
>
> It is not related to API compatibility per se, but very related to better API
> consumption and a low hanging fruit we could start with, since we have the
> metadata already

+1

>
>>> 2) Have option for the ipa tool to send version-less command to the server
>>> which should thus behave as if it is the same version. Bonus points if defaults
>>> are not filled in this case to prevent unrecoverable Unkown Option errors.
>>>
>>> https://fedorahosted.org/freeipa/ticket/4768
>>
>> Not sending version and not computing defaults are very different things and
>> their implemetantion will be very different too. I would not mix them together.
>
> We are now getting more in the design, but the idea was that sending the
> defaults may force server to refuse serving the command even if the caller did
> not explicitly requested that option. Even if the caller did not care about the
> new default option in 4.x, he would not be able to call the command as it would
> be always sent to the old server.

+1 that not sending defaults is essential for this case. IMHO we should 
not send them at all.

>
>>> Rest would be left for later releases. Please holler if there is disagreement
>>> with this plan.
>>
>> I agree with Nathaniel that we should do thin client ASAP.
>
> I agree too, but given it is not realistic for 4.2, we need to do at least
> something in 4.2 for projects which need to use the CLI against older versions.
>
> Skipping version and client defaults seemed as the low hanging fruit that could
> help them. If there is a better idea about what else can be done in 4.2, I am
> open to it.
>
> Martin
>


-- 
Petr Vobornik