Sometimes incompatible changes are unavoidable, but it's important to maintain the same API and CLI to avoid disruptions. In that case the changes should be implemented as a new API, the old API should be preserved for backward compatibility, and the CLI should be updated to use the new API.

However, in the current IPA framework it's not possible since API and the CLI are defined in the same class so they will share the same name and the same parameters. Ideally API and CLI should be defined in a separate classes. However, to minimize the changes the framework can be enhanced to allow an API to generate a different CLI name.

For example, currently the vault API and CLI have a 'service' parameter:

class vault_find(LDAPSearch):
    takes_options = (
        Str(
            'service?',
            doc=_('Service name of the service vault'),
        ),
    )

The vault object currently has 'user' and 'group' members:

class vault(LDAPObject):
    attribute_members = {
        'owner': ['user', 'group'],
        'member': ['user', 'group'],
    }

It has been determined that the vault object should have a 'service' member as well. However, the 'service' cannot be added to the vault object because it will automatically generate a 'service' parameter that will conflict with the existing 'service' parameter in the API and CLI.

To solve the problem, a new vault object should be created with the proper members:

class vault2(LDAPObject):
    attribute_members = {
        'owner': ['user', 'group', 'service'],
        'member': ['user', 'group', 'service'],
    }

To avoid conflicts the new API should use a different parameter name (e.g. servicename). To maintain the same user experience the new CLI should use the same command name (e.g. vault-find) and parameter name (e.g. service).

For this to work, the framework should be enhanced to provide a method/variable (e.g. Command.get_cli_name()) that can be overridden to allow an API to define a different CLI name.

class vault2_find(LDAPSearch):
    takes_options = (
        Str(
            'servicename?',
            cli_name='service', # map servicename to service
            doc=_('Service name of the service vault'),
        ),
    )

    # map vault2_find to vault-find
    def get_cli_name(self):
        return 'vault-find'

class vault_find(LDAPSearch):
    # disable the old vault-find
    NO_CLI = True

Please note that this situation might happen with other plugins as well, not just vault. Without the new plugin backward compatibility will not be possible. Without the framework enhancement, users will either have to use different commands (e.g. vault2-find).

Proposed milestone: 4.2.1