Extend API documentation

This includes:

* Section about command/param info in usage guide
* Section about metadata retrieval in usage guide
* Guide about differences between CLI and API
* Access control guide (management of roles, privileges and
  permissions).
* Guide about API contexts
* JSON-RPC usage guide and JSON-to-Python conversion
* Notes about types in API Reference

Signed-off-by: Antonio Torres <antorres@redhat.com>
Reviewed-By: Alexander Bokovoy <abokovoy@redhat.com>
Reviewed-By: Rob Crittenden <rcritten@redhat.com>

doc/api/A6Record.md

@@ -3,3 +3,5 @@
 
 # A6Record
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A6 DNS record.

doc/api/AAAARecord.md

@@ -3,3 +3,5 @@
 
 # AAAARecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+AAAA DNS record.

doc/api/AFSDBRecord.md

@@ -3,3 +3,5 @@
 
 # AFSDBRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+AFSDB DNS record.

doc/api/APLRecord.md

@@ -3,3 +3,5 @@
 
 # APLRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+APL DNS record.

doc/api/ARecord.md

@@ -3,3 +3,5 @@
 
 # ARecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A DNS record.

doc/api/AccessTime.md

@@ -3,3 +3,7 @@
 
 # AccessTime
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Access time parameter type.
+
+Accepts values conforming to generalizedTime as defined in RFC 4517 section 3.3.13 without time zone information.

doc/api/Any.md

@@ -3,3 +3,5 @@
 
 # Any
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter capable of holding values of any type. For internal use only.

doc/api/BinaryFile.md

@@ -3,3 +3,5 @@
 
 # BinaryFile
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Binary file parameter type.

doc/api/Bool.md

@@ -3,3 +3,5 @@
 
 # Bool
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for boolean values (stored in the ``bool`` type).

doc/api/Bytes.md

@@ -3,3 +3,9 @@
 
 # Bytes
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for binary data (stored in the ``str`` type).
+This class is named *Bytes* instead of *Str* so it's aligned with the
+Python v3 ``(str, unicode) => (bytes, str)`` clean-up.
+See: http://docs.python.org/3.0/whatsnew/3.0.html
+Also see the `Str` parameter.

doc/api/BytesEnum.md

@@ -3,3 +3,5 @@
 
 # BytesEnum
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Enumerable for binary data (stored in the ``str`` type).

doc/api/CERTRecord.md

@@ -3,3 +3,5 @@
 
 # CERTRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+CERT DNS record.

doc/api/CNAMERecord.md

@@ -3,3 +3,5 @@
 
 # CNAMERecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+CNAME DNS record.

doc/api/DHCIDRecord.md

@@ -3,3 +3,5 @@
 
 # DHCIDRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DHCID DNS record.

doc/api/DLVRecord.md

@@ -3,3 +3,5 @@
 
 # DLVRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DLV DNS record.

doc/api/DNAMERecord.md

@@ -3,3 +3,5 @@
 
 # DNAMERecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DNAME DNS record.

doc/api/DNOrURL.md

@@ -3,3 +3,7 @@
 
 # DNOrURL
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DN parameter that allows, and strips, a "ldap:///" prefix on input.
+
+Used for ``subtree`` to maintain backward compatibility.

doc/api/DNParam.md

@@ -3,3 +3,5 @@
 
 # DNParam
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+LDAP DN.

doc/api/DNSNameParam.md

@@ -3,3 +3,8 @@
 
 # DNSNameParam
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Domain name parameter type.
+
+* `only_absolute`: a domain name has to be absolute (makes it absolute from unicode input)
+* `only_relative`: a domain name has to be relative

doc/api/DNSRecord.md

@@ -3,3 +3,5 @@
 
 # DNSRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Base class for DNS records, subclass of `Str`.

doc/api/DSRecord.md

@@ -3,3 +3,5 @@
 
 # DSRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DS DNS record.

doc/api/Data.md

@@ -3,3 +3,9 @@
 
 # Data
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Base class for the `Bytes` and `Str` parameters.
+
+Previously `Str` was as subclass of `Bytes`.  Now the common functionality
+has been split into this base class so that ``isinstance(foo, Bytes)`` wont
+be ``True`` when ``foo`` is actually an `Str` instance (which is confusing).

doc/api/DateTime.md

@@ -3,3 +3,17 @@
 
 # DateTime
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+DateTime parameter type.
+
+Accepts LDAP Generalized time without in the following format:
+   '%Y%m%d%H%M%SZ'
+
+Accepts subset of values defined by ISO 8601:
+    '%Y-%m-%dT%H:%M:%SZ'
+    '%Y-%m-%dT%H:%MZ'
+    '%Y-%m-%dZ'
+
+Also accepts above formats using ' ' (space) as a separator instead of 'T'.
+
+Refer to the `man strftime` for the explanations for the %Y,%m,%d,%H.%M,%S.

doc/api/Decimal.md

@@ -3,3 +3,10 @@
 
 # Decimal
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for floating-point values (stored in the ``Decimal`` type).
+
+Python Decimal type helps overcome problems tied to plain "float" type,
+e.g. problem with representation or value comparison. In order to safely
+transfer the value over RPC libraries, it is being converted to string
+which is then converted back to Decimal number.

doc/api/Dict.md

@@ -3,3 +3,5 @@
 
 # Dict
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for dictionary.

doc/api/Enum.md

@@ -3,3 +3,5 @@
 
 # Enum
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Base class for parameters with enumerable values.

doc/api/File.md

@@ -3,3 +3,7 @@
 
 # File
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Text file parameter type.
+
+Accepts file names and loads their content into the parameter value.

doc/api/Flag.md

@@ -3,3 +3,35 @@
 
 # Flag
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A boolean parameter that always gets filled in with a default value.
+
+This `Bool` subclass forces ``autofill=True`` in `Flag.__init__()`.  If no
+default is provided, it also fills in a default value of ``False``.
+Lastly, unlike the `Bool` class, the default must be either ``True`` or
+``False`` and cannot be ``None``.
+
+For example:
+```
+>>> flag = Flag('my_flag')
+>>> (flag.autofill, flag.default)
+(True, False)
+```
+
+To have a default value of ``True``, create your `Flag` intance with
+``default=True``.  For example:
+
+```
+>>> flag = Flag('my_flag', default=True)
+>>> (flag.autofill, flag.default)
+(True, True)
+```
+
+Also note that creating a `Flag` instance with ``autofill=False`` will have
+no effect.  For example:
+
+```
+>>> flag = Flag('my_flag', autofill=False)
+>>> flag.autofill
+True
+```

doc/api/ForwardRecord.md

@@ -3,3 +3,5 @@
 
 # ForwardRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Forward DNS record.

doc/api/HINFORecord.md

@@ -3,3 +3,5 @@
 
 # HINFORecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+HINFO DNS record.

doc/api/HIPRecord.md

@@ -3,3 +3,5 @@
 
 # HIPRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+HIP DNS record.

doc/api/HostPassword.md

@@ -3,3 +3,9 @@
 
 # HostPassword
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A data type for host passwords to not log password values.
+
+The `Password` type cannot be used because it disallows
+setting a password on the command-line which would break
+backwards compatibility.

doc/api/IA5Str.md

@@ -3,3 +3,5 @@
 
 # IA5Str
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+An IA5String per RFC 4517.

doc/api/IPSECKEYRecord.md

@@ -3,3 +3,5 @@
 
 # IPSECKEYRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+IPSECKEY DNS record.

doc/api/Int.md

@@ -3,3 +3,5 @@
 
 # Int
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for integer values (stored in the ``int`` type).

doc/api/IntEnum.md

@@ -3,3 +3,5 @@
 
 # IntEnum
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Enumerable for integer data (stored in the ``int`` type).

doc/api/KEYRecord.md

@@ -3,3 +3,5 @@
 
 # KEYRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+KEY DNS record.

doc/api/KXRecord.md

@@ -3,3 +3,5 @@
 
 # KXRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+KX DNS record.

doc/api/LOCRecord.md

@@ -3,3 +3,5 @@
 
 # LOCRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+LOC DNS record.

doc/api/MDRecord.md

@@ -3,3 +3,5 @@
 
 # MDRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+MD DNS record.

doc/api/MINFORecord.md

@@ -3,3 +3,5 @@
 
 # MINFORecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+MINFO DNS record.

doc/api/MXRecord.md

@@ -3,3 +3,5 @@
 
 # MXRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+MX DNS record.

doc/api/NAPTRRecord.md

@@ -3,3 +3,5 @@
 
 # NAPTRRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+NAPTR DNS record.

doc/api/NSECRecord.md

@@ -3,3 +3,5 @@
 
 # NSECRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+NSEC DNS record.

doc/api/NSRecord.md

@@ -3,3 +3,5 @@
 
 # NSRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+NS DNS record.

doc/api/NXTRecord.md

@@ -3,3 +3,5 @@
 
 # NXTRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+NXT DNS record.

doc/api/Number.md

@@ -3,3 +3,5 @@
 
 # Number
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Base class for the `Int` and `Decimal` parameters.

doc/api/OTPTokenKey.md

@@ -3,3 +3,5 @@
 
 # OTPTokenKey
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A binary password type specified in base32.

doc/api/PTRRecord.md

@@ -3,3 +3,5 @@
 
 # PTRRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+PTR DNS record.

doc/api/Password.md

@@ -3,3 +3,5 @@
 
 # Password
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for passwords (stored in the ``unicode`` type).

doc/api/Principal.md

@@ -3,3 +3,5 @@
 
 # Principal
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Kerberos principal name.

doc/api/RPRecord.md

@@ -3,3 +3,5 @@
 
 # RPRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+RP DNS record.

doc/api/RRSIGRecord.md

@@ -3,3 +3,5 @@
 
 # RRSIGRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+RRSIG DNS record.

doc/api/SIGRecord.md

@@ -3,3 +3,5 @@
 
 # SIGRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+SIG DNS record.

doc/api/SPFRecord.md

@@ -3,3 +3,5 @@
 
 # SPFRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+SPF DNS record.

doc/api/SRVRecord.md

@@ -3,3 +3,5 @@
 
 # SRVRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+SRV DNS record.

doc/api/SSHFPRecord.md

@@ -3,3 +3,5 @@
 
 # SSHFPRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+SSHFP DNS record.

doc/api/SerialNumber.md

@@ -3,3 +3,5 @@
 
 # SerialNumber
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Certificate serial number parameter type.

doc/api/Str.md

@@ -3,3 +3,12 @@
 
 # Str
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+A parameter for Unicode text (stored in the ``unicode`` type).
+
+This class is named `Str` instead of `Unicode` so it's aligned with the
+Python v3 ``(str, unicode) => (bytes, str)`` clean-up.  
+
+See: http://docs.python.org/3.0/whatsnew/3.0.html
+
+Also see the `Bytes` parameter.

doc/api/StrEnum.md

@@ -3,3 +3,17 @@
 
 # StrEnum
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Enumerable for Unicode text (stored in the ``unicode`` type).
+
+For example:
+
+```
+>>> enum = StrEnum('my_enum', values=(u'One', u'Two', u'Three'))
+>>> enum.validate(u'Two', 'cli') is None
+True
+>>> enum.validate(u'Four', 'cli')
+Traceback (most recent call last):
+  ...
+ValidationError: invalid 'my_enum': must be one of 'One', 'Two', 'Three'
+```

doc/api/TLSARecord.md

@@ -3,3 +3,5 @@
 
 # TLSARecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+TLSA DNS record.

doc/api/TXTRecord.md

@@ -3,3 +3,5 @@
 
 # TXTRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+TXT DNS record.

doc/api/URIRecord.md

@@ -3,3 +3,5 @@
 
 # URIRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+URI DNS record.

doc/api/UnsupportedDNSRecord.md

@@ -3,3 +3,6 @@
 
 # UnsupportedDNSRecord
 [//]: # (ADD YOUR NOTES BELOW. THESE WILL BE PICKED EVERY TIME THE DOCS ARE REGENERATED. //end)
+
+Records which are not supported by IPA, but we allow to show them if LDAP
+contains these records.

doc/api/access_control_guide.md

@@ -0,0 +1,66 @@
+# Access control examples
+
+IPA provides a way to manage delegation of rights. Permissions allows to define
+certain management actions, which can then be grouped in privileges. These
+privileges can then be added to roles, which can be assigned to users and
+groups.
+
+- [Access control examples](#access-control-examples)
+  - [Managing permissions](#managing-permissions)
+  - [Managing privileges](#managing-privileges)
+  - [Managing roles](#managing-roles)
+  - [Assigning roles to users and groups](#assigning-roles-to-users-and-groups)
+
+## Managing permissions
+
+Add a permission for creating users.
+
+```python
+api.Command.permission_add("Create users", ipapermright='add', type='user')
+```
+
+Add a permission for managing group membership.
+
+```python
+api.Command.permission_add("Manage group membership", ipapermright='write', type='group', attrs="member")
+```
+
+## Managing privileges
+
+Add a privilege for user creation process (creating user, adding it to groups,
+manage user certificates).
+
+```python
+api.Command.permission_add("Create users", ipapermright='add', type='user')
+api.Command.permission_add("Manage group membership", ipapermright='write', type='group', attrs="member")
+api.Command.permission_add("Manage User certificates", ipapermright='write', type='user', attrs='usercertificate')
+
+api.Command.privilege_add("User creation")
+api.Command.privilege_add_permission("User creation", permission="Create users")
+api.Command.privilege_add_permission("User creation", permission="Manage group membership")
+api.Command.privilege_add_permission("User creation", permission="Manage User certificates")
+```
+
+## Managing roles
+
+Add a role with the privilege created earlier.
+
+```python
+api.Command.role_add("usermanager", description="Users manager")
+api.Command.role_add_privilege("usermanager", privilege="User creation")
+```
+
+## Assigning roles to users and groups
+
+Assign the role `usermanager` to user `bob`.
+
+```python
+api.Command.role_add_member("usermanager", user="bob")
+```
+
+Users, groups, hosts and hostgroups may be members of a role. Assign the
+`usermanager` role to `managers` group.
+
+```python
+api.Command.role_add_member("usermanager", group="managers")
+```

doc/api/api_cli_differences.md

@@ -0,0 +1,47 @@
+# Differences between API and CLI usage
+
+While the functionality between API and CLI is mostly the same, there are some
+difference in their usage that should be taken into account.
+
+- [Differences between API and CLI usage](#differences-between-api-and-cli-usage)
+  - [Command naming](#command-naming)
+  - [Parameter naming](#parameter-naming)
+  - [Date format](#date-format)
+  - [CLI-specific tools](#cli-specific-tools)
+
+## Command naming
+
+Commands in the CLI are constructed by specifying a topic and an action, with a
+hyphen between them: `user-add`, `group-mod`, `host-del`. When accessing through
+the API, the topic and the action are divided by an underscore instead:
+`user_add`, `group_mod`, `host_del`. All available commands can be found below
+`api.Command` after the API is initialized.
+
+## Parameter naming
+
+When managing plugins through the CLI, their parameters have different names
+than the API, where names are the same as the LDAP attributes. For example,
+`user-add` takes the `first` parameter in the CLI. However, this is named
+`givenname` when calling `user_add` through the Python API.
+
+## Date format
+
+When passing dates through the CLI, multiple date string formats are available:
+
+* %Y%m%d%H%M%SZ
+* %Y-%m-%dT%H:%M:%SZ
+* %Y-%m-%dT%H:%MZ
+* %Y-%m-%dZ
+* %Y-%m-%d %H:%M:%SZ
+* %Y-%m-%d %H:%MZ
+
+When using the API, apart from these formats, the Python built-in `datetime` class
+can be used as well.
+
+## CLI-specific tools
+
+FreeIPA provides multiple tools that are mainly useful for CLI usage:
+
+* `console`: starts an interactive Python console with an IPA API object already initialized.
+* `help`: shows help about topics and commands, including examples for the CLI.
+* `show-mappings`: shows the mapping between CLI parameter names and LDAP attributes.

doc/api/basic_usage.md

@@ -6,6 +6,8 @@
   - [Running commands](#running-commands)
   - [Passing arguments and options](#passing-arguments-and-options)
   - [Retrieving output](#retrieving-output)
+  - [Displaying information about commands and parameters](#displaying-information-about-commands-and-parameters)
+  - [API Contexts](#api-contexts)
   - [Batch operations](#batch-operations)
 
 ## Introduction
@@ -18,7 +20,12 @@ that can be accessed through Python, allowing users to interact with FreeIPA
 programatically and develop custom tools to respond to specific needs not 
 covered by the main interfaces. For users looking to perform stateless
 operations or manage deployments with statically defined properties,
-[ansible-freeipa](https://github.com/freeipa/ansible-freeipa) is recommended instead.
+[ansible-freeipa](https://github.com/freeipa/ansible-freeipa) is recommended
+instead.
+
+While FreeIPA API provides a JSON-RPC interface, it is recommended to access the
+API through Python instead, since it automates important parts such as the
+metadata retrieval from the server, which allows to list all available commands.
 
 ## Initializing API access
 
@@ -169,6 +176,86 @@ The output contains four sections:
 * `messages`: Different diagnostic information provided by FreeIPA after the operation.
 * `summary`: A summary of the operation.
 
+## Displaying information about commands and parameters
+
+All available information about commands and their parameters is provided in the
+API Reference. Additionally, the API provides tools to display this information. 
+It can be retrieved using the `command_show` and `param_show` commands.
+
+```python
+api.Command.command_show("user_add")
+```
+
+```python
+{
+    "result": {
+        "name": "user_add",
+        "version": "1",
+        "full_name": "user_add/1",
+        "doc": "Add a new user.",
+        "topic_topic": "user/1",
+        "obj_class": "user/1",
+        "attr_name": "add",
+    },
+    "value": "user_add",
+    "messages": [
+        {
+            "type": "warning",
+            "name": "VersionMissing",
+            "message": "API Version number was not sent, forward compatibility not guaranteed. Assuming server's API version, 2.251",
+            "code": 13001,
+            "data": {"server_version": "2.251"},
+        }
+    ],
+    "summary": None,
+}
+```
+
+For listing all available parameters for a certain command, the `param_find`
+command can be used. We can additionally show information of a certain
+parameter from a command using `param_show`.
+
+
+```python
+api.Command.param_show("user_add", name="givenname")
+```
+
+```python
+{
+    "result": {
+        "name": "givenname",
+        "type": "str",
+        "positional": False,
+        "cli_name": "first",
+        "label": "First name",
+    },
+    "value": "givenname",
+    "messages": [
+        {
+            "type": "warning",
+            "name": "VersionMissing",
+            "message": "API Version number was not sent, forward compatibility not guaranteed. Assuming server's API version, 2.251",
+            "code": 13001,
+            "data": {"server_version": "2.251"},
+        }
+    ],
+    "summary": None,
+}
+```
+
+## API Contexts
+
+As explained earlier, a context can be specified before initializing the API.
+The purpose of the context is to define the set of methods that can be
+performed. FreeIPA defines by default four major contexts:
+
+* `server`: plugins validate any arguments and options passed and then execute
+  the requested action.
+* `client`: plugins validate any arguments and options passed and then forward
+  the request to the FreeIPA server to execute.
+* `installer`: plugins specific to the installation process are loaded.
+* `updates`: plugins specific the update process are loaded.
+
 ## Batch operations
 
 Batch operations are useful for executing multiple commands at once, as it

doc/api/guides.rst

@@ -4,7 +4,10 @@ IPA API Guides
    :maxdepth: 1
 
    basic_usage.md
+   jsonrpc_usage.md
+   api_cli_differences.md
    user_management.md
    group_management.md
+   access_control_guide.md
    hbac_guide.md
    sudorule_management.md

doc/api/jsonrpc_usage.md

@@ -0,0 +1,135 @@
+# JSON-RPC API usage
+
+Apart from Python, the FreeIPA API is also available through HTTPS exchanging
+requests in JSON-RPC format.
+
+## Basic usage
+
+Before sending requests to the FreeIPA server, we need to properly authenticate.
+
+It is possible to authenticate both through Kerberos and password.
+
+### Kerberos authentication
+
+To authenticate via Kerberos, it is needed to have actual credentials in the
+credentials cache first. After this, we need to send a login request to the
+FreeIPA endpoint, `https://$IPAHOSTNAME/ipa/session/login_kerberos`.
+
+```bash
+$ export KRB5CCNAME=FILE:/path/to/ccache
+$ export COOKIEJAR=/path/to/my.cookie
+$ export IPAHOSTNAME=ipa-master.example.com
+$ kinit -k -t /path/to/service.keytab service/ipa-client.example.com
+$ curl -v  \
+        -H referer:https://$IPAHOSTNAME/ipa  \
+        -c $COOKIEJAR -b $COOKIEJAR \
+        --cacert /etc/ipa/ca.crt  \
+        --negotiate -u : \
+        -X POST \
+        https://$IPAHOSTNAME/ipa/session/login_kerberos
+```
+
+If authentication was successful, `$COOKIEJAR` will contain all session cookies
+returned from the server. We will need to pass this with every request we send
+to the server.
+
+### Password authentication
+
+For password authentication, we just need to post it over HTTPS.
+
+```bash
+$ export COOKIEJAR=/path/to/my.cookie
+$ export IPAHOSTNAME=ipa-master.example.com
+$ s_username=admin s_password=mYSecReT1P2 curl -v  \
+        -H referer:https://$IPAHOSTNAME/ipa  \
+        -H "Content-Type:application/x-www-form-urlencoded" \
+        -H "Accept:text/plain"\
+        -c $COOKIEJAR -b $COOKIEJAR \
+        --cacert /etc/ipa/ca.crt  \
+        --data "user=$s_username&password=$s_password" \
+        -X POST \
+        https://$IPAHOSTNAME/ipa/session/login_password
+```
+
+Same as kerberos authentication, we will need to pass the sessions cookies with
+every request.
+
+### Request and Response format
+
+A JSON-RPC request consists of three properties:
+
+* `method`: A string containing the name of the name that will be called.
+* `params`: the array of parameters for the command.
+* `id`: the request id, it can be of any type, the response will match it.
+
+The response received from the server consists of four properties:
+
+* `result`: The returned Object from the command. If the command failed, this
+  will be null.
+* `principal`: The Kerberos principal under which identity the command was performed.
+* `error`: An Error object containing information about the command if it
+  failed. If it succeeded, this will be null.
+* `ìd`: An ID matching the request this response is replying to.
+
+### Sending a request
+
+Requests should be sent to the API endpoint
+`https://$IPAHOSTNAME/ipa/session/json` over HTTPS. The content type must be set
+to `application/json` and session cookies obtained when authentication must be
+passed with the request.
+
+An example request for the `user_find` command would be:
+
+```bash
+curl -v  \
+	-H referer:https://$IPAHOSTNAME/ipa  \
+        -H "Content-Type:application/json" \
+        -H "Accept:applicaton/json"\
+        -c $COOKIEJAR -b $COOKIEJAR \
+        --cacert /etc/ipa/ca.crt  \
+        -d  '{"method":"user_find","params":[[""],{}],"id":0}' \
+        -X POST \
+        https://$IPAHOSTNAME/ipa/session/json
+```
+
+An easy way to understand how IPA requests are built is via the CLI, by passing
+the `-vv` option to an IPA command.
+
+```bash
+$ ipa -vv user-find 
+ipa: INFO: Request: {
+    "id": 0,
+    "method": "user_find/1",
+    "params": [
+        [],
+        {
+            "version": "2.251"
+        }
+    ]
+}
+
+[...]
+```
+
+## Converting JSON-RPC requests to Python
+
+FreeIPA provides methods to convert JSON-RPC requests to Python format. This is
+included in the `freeipa-python-ipaserver` package in Fedora.
+
+```python
+from ipaserver.rpcserver import jsonserver
+
+json_request = '{"method":"user_find","params":[[""],{}],"id":0}'
+j = jsonserver(api) # `api` is the initialized IPA API object
+
+(name, args, opts, response_id) = j.unmarshal(json_request)
+
+result = api.Command[name](*args, **opts)
+```
+
+## Reporting issues
+
+To report issues related to API usage, they should be reproducible using the API
+through Python, in order to discard errors related to misconstruction of
+JSON-RPC requests. These requests can be converted to Python using the steps
+mentioned earlier.