docs: improve permissions documentation

docs/03-endpoints/api-admin/permissions.md

@@ -5,12 +5,29 @@
 
 # Permissions Endpoint
 
-##Permission Operations:
+For an extensive explanation on how DSP permissions are implemented, see
+[here](../../05-internals/design/api-admin/administration.md#permissions).
 
-**Note:** For the following operations, the requesting user must be either a `systemAdmin`or 
-a `projectAdmin`.
+| Route                                                   | Operations | Explanation                                                                                                                                                                               |
+| ------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/admin/permissions/{projectIri}`                       | `GET`      | [get all permissions of a project](#getting-permissions)                                                                                                                                  |
+| `/admin/permissions/ap/{projectIri}`                    | `GET`      | [get all administrative permissions of a project](#getting-permissions)                                                                                                                   |
+| `/admin/permissions/ap/{projectIri}/{groupIri}`         | `GET`      | [get all administrative permissions of a group](#getting-permissions)                                                                                                                     |
+| `/admin/permissions/doap/{projectIri}`                  | `GET`      | [get all default object access permissions of a project](#getting-permissions)                                                                                                            |
+| `/admin/permissions/ap`                                 | `POST`     | [create a new administrative permission](#creating-new-administrative-permissions)                                                                                                        |
+| `/admin/permissions/doap`                               | `POST`     | [create a new default object access permission](#creating-new-default-object-access-permissions)                                                                                          |
+| `/admin/permissions/{permissionIri}/group`              | `PUT`      | [update for which group an administrative or default object access permission is used](#updating-a-permissions-group)                                                                     |
+| `/admin/permissions/{permissionIri}/hasPermission`      | `PUT`      | [update the scope of an administrative or default object access permission](#updating-a-permissions-scope), i.e. what permissions are granted to which group when this permission applies |
+| `/admin/permissions/{doap_permissionIri}/resourceClass` | `PUT`      | [update for which resource class a default object access permission applies](#updating-a-default-object-access-permissions-resource-class)                                                |
+| `/admin/permissions/{doap_permissionIri}/property`      | `PUT`      | [update for which property a default object access permission applies](#updating-a-default-object-access-permissions-property)                                                            |
+| `/admin/permissions/{permissionIri}`                    | `DELETE`   | [delete an administrative or default object access permission](#deleting-a-permission)                                                                                                    |
+
+## Permission Operations
+
+**Note:** For the following operations, the requesting user must be either a `systemAdmin`or a `projectAdmin`.
+
+### Getting Permissions
 
-### Getting Permissions: 
 - `GET: /admin/permissions/<projectIri>` : return all permissions for a project.
 As a response, the IRI and the type of all `permissions` of a project are returned.
 
@@ -25,7 +42,7 @@ for the group is returned.
 permissions for a project. As a response, all `default_object_acces_permissions` of a 
 project are returned. 
 
-### Creating New Administrative Permissions:
+### Creating New Administrative Permissions
 
 - `POST: /admin/permissions/ap`: create a new administrative permission. The type of 
 permissions, the project and group to which the permission should be added must be 
@@ -45,7 +62,8 @@ included in the request body, for example:
 }
 ``` 
 
-In addition, in the body of the request, it is possible to specify a custom IRI (of [Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) for a permission through
+In addition, in the body of the request, it is possible to specify a custom IRI (of 
+[DSP IRI](../api-v2/knora-iris.md#iris-for-data) form) for a permission through
 the `@id` attribute which will then be assigned to the permission; otherwise the permission will get a unique random IRI.
 A custom permission IRI must be `http://rdfh.ch/permissions/PROJECT_SHORTCODE/` (where `PROJECT_SHORTCODE`
 is the shortcode of the project that the permission belongs to), plus a custom ID string. For example:
@@ -105,7 +123,7 @@ Therefore, it is not possible to create new administrative permissions for the P
 a project. However, the default permissions set for these groups can be modified (See [update permission](./permissions.md#updating-a-permissions-scope)).
 
 
-### Creating New Default Object Access Permissions:
+### Creating New Default Object Access Permissions
 
 - `POST: /admin/permissions/doap` : create a new default object access permission. 
 A single instance of `knora-admin:DefaultObjectAccessPermission` must
@@ -199,10 +217,10 @@ ProjectAdmin and ProjectMember groups (See [Default set of permissions for a new
 Therefore, it is not possible to create new default object access permissions for the ProjectAdmin and ProjectMember 
 groups of a project. However, the default permissions set for these groups can be modified; see below for more information.
 
-### Updating a Permission's Group:
+### Updating a Permission's Group
 
 - `PUT: /admin/permissions/<permissionIri>/group` to change the group for which an administrative or a default object 
-access permission, identified by it IRI `<permissionIri>`, is defined. The request body must contain the IRI of the new 
+access permission, identified by its IRI `<permissionIri>`, is defined. The request body must contain the IRI of the new 
 group as below:
 
 ```json
@@ -216,7 +234,7 @@ with the new group. Otherwise, if the default object access permission was defin
 the combination of both, the permission will be defined for the newly specified group and its previous 
 `forResourceClass` and `forProperty` values will be deleted.
 
-### Updating a Permission's Scope:
+### Updating a Permission's Scope
 
 - `PUT: /admin/permissions/<permissionIri>/hasPermissions` to change the scope of permissions assigned to an administrative
   or a default object access permission identified by it IRI, `<permissionIri>`. The request body must contain the new set 
@@ -238,9 +256,13 @@ Each permission item given in `hasPermissions`, must contain the necessary param
 permission. For example, if you wish to change the scope of an administrative permission, follow the 
 [guidelines](#creating-new-administrative-permissions) for the
 content of its `hasPermissions` property. Similarly, if you wish to change the scope of a default object access permission, 
-follow the [guidelines](#creating-new-default-object-access-permissions) given about the content of its `hasPermissions` property.
+follow the [guidelines](#creating-new-default-object-access-permissions) given about the content of its `hasPermissions` property.  
+Either the `name` or the `permissionCode` must be present; it is not necessary to provide both.
+
+The previous permission set is *replaced* by the new permission set. In order to remove a permission for a group
+entirely, you can provide a new set of permissions, leaving out the permission specification for the group.
 
-### Updating a Default Object Access Permission's Resource Class:
+### Updating a Default Object Access Permission's Resource Class
 
 - `PUT: /admin/permissions/<doap_permissionIri>/resourceClass` to change the resource class for which a default object 
 access permission, identified by it IRI `<doap_permissionIri>`, is defined. This operation is only valid for 
@@ -256,7 +278,7 @@ Note that if the default object access permission was originally defined for a g
 will be defined for the given resource class instead of the group. That means the value of the `forGroup` will 
 be deleted.
 
-### Updating a Default Object Access Permission's Property:
+### Updating a Default Object Access Permission's Property
 
 - `PUT: /admin/permissions/<doap_permissionIri>/property` to change the property for which a default object 
 access permission, identified by it IRI `<doap_permissionIri>`, is defined. This operation is only valid for 
@@ -271,7 +293,7 @@ Note that if the default object access permission was originally defined for a g
 will be defined for the given property instead of the group. That means the value of the `forGroup` will 
 be deleted.
 
-### Deleting a permission:
+### Deleting a Permission
 
 - `DELETE: /admin/permissions/<permissionIri>` to delete an administrative, or a default object access permission. The 
 IRI of the permission must be given in encoded form. 

docs/05-internals/design/api-admin/administration.md

@@ -72,6 +72,8 @@ the built-in group to `knora-admin`, e.g., `knora-admin:KnownUser` where
 
 ## Permissions
 
+The permissions API endpoint is described [here](../../../03-endpoints/api-admin/permissions.md).
+
 Up until know, we have mentioned two groups of permissions. The first
 called *object access permissions*, which contains permissions that
 point from explicit **objects** (resources/values) to groups. The second