[Freeipa-users] Optionistic approach for new DNS API

[Martin Kosek]

Hello all,

we just had a good discussion with Rob and Endi about different approach
to the new DNS API. Current DNS API proposal (patches 174-176)
introduced new API based on different commands, e.g. for MX RR type:

ipa dnsrecord-mx-add ZONE NAME --preference=0 --exchanger=server1.example.com.
ipa dnsrecord-mx-mod ZONE NAME "0 server1.example.com." --preference=1
ipa dnsrecord-mx-show ZONE NAME

As a side effect, this would introduce many new commands
(dnsrecord-mx-add/mod/show, dnsrecord-loc-add/mod/show, ...) which may
of course be confusing.

Endi proposed an different approach to use rather per-type options
instead of commands, which I think is really interesting to think about.
I will summarize how the API may look like.

Changes to DNS module commands:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- no new DNS command would be implemented, we would just enhance current
dns record commands:
  * dnsrecord-add, dnsrecord-mod, dnsrecord-del and dnsrecord-find
- all changes must be compatible with 2.x clients, changes to output
shall be triggered by 3.x option

Command Structure:
~~~~~~~~~~~~~~~~~~
- we would introduce --type option which would trigger the command to
use the new structured DNS options, i.e.:

ipa dnsrecord-add ZONE NAME --type=mx --preference=0 --exchanger=server1.example.com.

or

ipa dnsrecord-mod ZONE NAME VALUE? --type=mx --preference=0

or

ipa dnsrecord-del ZONE NAME --type=mx --preference=0 --exchanger=server1.example.com.

- SHOW and FIND commands do not need this new --type parameter


Command Output:
~~~~~~~~~~~~~~~
- we would introduce a new --structured option which would switch
command output to "structured way" and present rather parsed DNS records
instead of raw DNS values (this is also needed for 2.x compatibility).

For JSON output we may get:

{
     idnsname: 'foo',
     records: [
         {
             type: 'a',
             data: '10.10.10.10',
             ip_address: '10.10.10.10'
         },
         {
             type: 'cname',
             data: 'bar.example.com.',
             hostname: 'bar.example.com.'
         },
         {
             type: 'cname',
             data: 'bar2.example.com.',
             hostname: 'bar2.example.com.'
         },
     ]
}

instead of

{
     idnsname: 'foo',
     arecord: [
         '10.10.10.10'
     ],
     cnamerecord: [
         'bar.example.com.',
         'bar2.example.com.'
     ]
}

In CLI it may look like this:
# ipa dnsrecordmx-show example.com @ --structured
  Record name: @
    Record type: MX
    Data: 0 server1.example.com
    Preference: 0
    Exchanger: server1.example.com

    Record type: NS
    Data: vm-068.idm.lab.bos.redhat.com.
    Hostname: vm-068.idm.lab.bos.redhat.com.

instead of:

# ipa dnsrecord-show example.com @
  Record name: @
  MX record: 0 server1.example.com
  NS record: vm-068.idm.lab.bos.redhat.com.

Command help:
~~~~~~~~~~~~~
- since dnsrecord-add would accept all options from all DNS RR types,
its list would be overwhelming and not very helpful
- we can take advantage of OptionParser option groups. The help may look
like this:

$ ipa dnsrecord-add --help
Usage: ipa [global-options] dnsrecord-add DNSZONE NAME [options]

Options:
  -h, --help  show this help message and exit

SRV Options:
 --priority   Priority
 --weight     Weight
 --port       Port
 --target     Target

MX Options:
 --priority   Priority
 --exchanger  A host willing to act as a mail exchanger
...

Interactive mode in CLI:
~~~~~~~~~~~~~~~~~~~~~~~~
- ADD command:
  - when no option is passed to dnsrecord-add command, it may ask for
--type and then for the options specific for the particular type
- MOD command:
  - when no option is passed to dnsrecord-mod command, it may provide a
list of current DNS record values and ask for specific DNS record parts
to be changed for chosen value
- DEL command:
  - when no option is passed to dnsrecord-del command, it may provide a
list of current DNS record values remove the chosen value

Any comments, suggestions? Do you think that introducing these new
options in current dnsrecord-add/mod/show/del commands would be better
and more usable that introducing these capabilities in separate
commands?

Thanks,
Martin