From f4004b2525821285ac798b251a0a11ba42cc5daf Mon Sep 17 00:00:00 2001 From: Balduin Landolt <33053745+BalduinLandolt@users.noreply.github.com> Date: Wed, 30 Nov 2022 14:55:07 +0100 Subject: [PATCH] docs: improve permissions documentation (#2314) --- docs/03-endpoints/api-admin/permissions.md | 50 +++++++++++++------ .../design/api-admin/administration.md | 2 + 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/03-endpoints/api-admin/permissions.md b/docs/03-endpoints/api-admin/permissions.md index 05e3a0a57a..77314bcc66 100644 --- a/docs/03-endpoints/api-admin/permissions.md +++ b/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/` : 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//group` to change the group for which an administrative or a default object -access permission, identified by it IRI ``, is defined. The request body must contain the IRI of the new +access permission, identified by its IRI ``, 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//hasPermissions` to change the scope of permissions assigned to an administrative or a default object access permission identified by it IRI, ``. 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//resourceClass` to change the resource class for which a default object access permission, identified by it IRI ``, 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//property` to change the property for which a default object access permission, identified by it IRI ``, 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/` to delete an administrative, or a default object access permission. The IRI of the permission must be given in encoded form. diff --git a/docs/05-internals/design/api-admin/administration.md b/docs/05-internals/design/api-admin/administration.md index a733b88ffb..f42ca5f8db 100644 --- a/docs/05-internals/design/api-admin/administration.md +++ b/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