[Freeipa-devel] Designing better API compatibility

[Martin Kosek]

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

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

Rest would be left for later releases. Please holler if there is disagreement
with this plan.

Thanks,
Martin