[Freeipa-devel] Designing better API compatibility

[Jan Cholasta]

Dne 9.4.2015 v 09:45 Petr Vobornik napsal(a):
> 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.

I agree with that, I'm just saying it won't be as simple as it sounds 
and certainly not as simple as not sending the version.

>
>>
>>>> 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
>>
>
>


-- 
Jan Cholasta