Fedora Server Role D-BUS API Design Discussion

[Jan Safranek]

On 03/26/2014 12:17 AM, Miloslav Trmač wrote:
> 2014-03-25 18:14 GMT+01:00 Stephen Gallagher <sgallagh at redhat.com
> <mailto:sgallagh at redhat.com>>:
>> On 03/24/2014 05:02 PM, Miloslav Trmač wrote:
>>> 2014-03-19 14:47 GMT+01:00 Stephen Gallagher <sgallagh at redhat.com
> <mailto:sgallagh at redhat.com>
>>> Wouldn't it be cleaner to have generic ValidateSettings(settings)
>>> DeployRole(settings) as the abstraction used by the "universal"
>>> clients (with "settings" possibly having some universal settings,
>>> like our favorite firewall_enabled_after_deploy, but mostly
>>> role-specific, only using a standard format, perhaps JSON or some
>>> object graph with similar capabilities)?
>>
>> That's an idea. I'm not sure it's doing anything other than moving the
>> problem to the settings object instead of the method call, but *shrug*.
> 
> Right, it would be even better to provide role-specific APIs (or a
> generic API with schema enforcement) to change values within the
> settings object :)  in order to make typos in settings names obvious,
> and that point it is really similar.
> 
> It does only one structurally significant thing: encode the "settings
> format" (JSON/whatever) as a canonical way to describe/dump/persistently
> store role deployment configuration, giving the API users precisely the
> same facilities they have during installation.

What UDisks and storaged do, they have 'options' parameter of nearly all
methods, e.g. BlockDevice.Format(fstype, options).

The options parameter is just dictionary string -> variant, where
variant can be literally anything, int, string, array, dictionary of
arrays, etc. I think you could represent it as JSON or XML to users.

Supported keys and allowed values are usually documented somewhere and
adding new key is not considered as API change, while adding a new
method parameter is.

See
http://udisks.freedesktop.org/docs/latest/gdbus-org.freedesktop.UDisks2.Block.html#gdbus-method-org-freedesktop-UDisks2-Block.Format
for example.


Also, UDisks has a 'Configuration' property for a block device, which
basically sets fstab / crypttab properties + it has methods to
manipulate it. I don't know how common is this approach.

See
http://udisks.freedesktop.org/docs/latest/gdbus-org.freedesktop.UDisks2.Block.html#gdbus-property-org-freedesktop-UDisks2-Block.Configuration

Jan