[Freeipa-devel] Designing better API compatibility

[Jan Cholasta]

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.

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

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

>
> Thanks,
> Martin
>


-- 
Jan Cholasta