[Freeipa-devel] Designing better API compatibility

[Martin Kosek]

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

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

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