Skip to content

Latest commit

 

History

History
199 lines (170 loc) · 9.24 KB

permissions.md

File metadata and controls

199 lines (170 loc) · 9.24 KB
Raw

Permissions Endpoint

##Permission Operations:

Note: For the following operations, the requesting user must be either a systemAdminor a projectAdmin.

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.

  • GET: /admin/permissions/ap/<projectIri>: return all administrative permissions for a project. As a response, all administrative_permissions of a project are returned.

  • GET: /admin/permissions/ap/<projectIri>/<groupIri>: return the administrative permissions for a project group. As a response, the administrative_permission defined for the group is returned.

  • GET: /admin/permissions/doap/<projectIri>: return all default object access permissions for a project. As a response, all default_object_acces_permissions of a project are returned.

Creating New 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 included in the request body, for example:
{
    "forGroup":"http://rdfh.ch/groups/0001/thing-searcher", 
    "forProject":"http://rdfh.ch/projects/0001", 
    "hasPermissions":[{"additionalInformation":null,"name":"ProjectAdminGroupAllPermission","permissionCode":null}]
}

In addition, in the body of the request, it is possible to specify a custom IRI (of Knora IRI 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:

"id": "http://rdfh.ch/permissions/0001/AP-with-customIri",

As a response, the created administrative permission and its IRI are returned as below:

{
    "administrative_permission": {
        "forGroup": "http://rdfh.ch/groups/0001/thing-searcher",
        "forProject": "http://rdfh.ch/projects/0001",
        "hasPermissions": [
            {
                "additionalInformation": null,
                "name": "ProjectAdminGroupAllPermission",
                "permissionCode": null
            }
        ],
        "iri": "http://rdfh.ch/permissions/0001/mFlyBEiMQtGzwy_hK0M-Ow"
    }
}

Note that during the creation of a new project, a default set of administrative permissions are added to its ProjectAdmin and ProjectMember groups (See Default set of permissions for a new project). Therefore, it is not possible to create new administrative permissions for the ProjectAdmin and ProjectMember groups of a project. However, the default permissions set for these groups can be modified (See update permission).

  • POST: /admin/permissions/doap : create a new default object access permission. A single instance of knora-admin:DefaultObjectAccessPermission must always reference a project, but can only reference either a group (knora-admin:forGroup property), a resource class (knora-admin:forResourceClass), a property (knora-admin:forProperty), or a combination of resource class and property. For example, to create a new default object access permission for a group of a project the request body would be
{
    "forGroup":"http://rdfh.ch/groups/0001/thing-searcher",
    "forProject":"http://rdfh.ch/projects/0001",
    "forProperty":null,
    "forResourceClass":null,
    "hasPermissions":[{"additionalInformation":"http://www.knora.org/ontology/knora-admin#ProjectMember","name":"D","permissionCode":7}]
}

Similar to the previous case a custom IRI can be assigned to a permission specified by the id in the request body. The example below shows the request body to create a new default object access permission with a custom IRI defined for a resource class of a specific project:

{
    "id": "http://rdfh.ch/permissions/00FF/DOAP-with-customIri",
    "forGroup":null,
    "forProject":"http://rdfh.ch/projects/00FF",
    "forProperty":null,
    "forResourceClass":"http://www.knora.org/ontology/00FF/images#bild",
    "hasPermissions":[{"additionalInformation":"http://www.knora.org/ontology/knora-admin#ProjectMember","name":"D","permissionCode":7}]
}

The response contains the newly created permission and its IRI, as:

{
    "default_object_access_permission": {
        "forGroup": null,
        "forProject": "http://rdfh.ch/projects/00FF",
        "forProperty": null,
        "forResourceClass": "http://www.knora.org/ontology/00FF/images#bild",
        "hasPermissions": [
            {
                "additionalInformation": "http://www.knora.org/ontology/knora-admin#ProjectMember",
                "name": "D",
                "permissionCode": 7
            }
        ],
        "iri": "http://rdfh.ch/permissions/00FF/DOAP-with-customIri"
    }
}

Note that during the creation of a new project, a set of default object access permissions are created for its ProjectAdmin and ProjectMember groups (See Default set of permissions for a new project). 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:

  • 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 group as below:
{
   "forGroup": "http://www.knora.org/ontology/knora-admin#ProjectMember"
}

When updating an administrative permission, its previous forGroup value will be replaced with the new one. When updating a default object access permission, if it originally had a forGroup value defined, it will be replaced with the new group. Otherwise, if the default object access permission was defined for a resource class or a property or 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:

  • 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 of permission types as below:
{
  "hasPermissions":[{"additionalInformation":"http://www.knora.org/ontology/knora-admin#ProjectMember","name":"D","permissionCode":7}]
}

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 updating a default object acceess permission. The IRI of the new resource class must be given in the request body as:
{
   "forResourceClass": "http://www.knora.org/ontology/0803/incunabula#book"
}

Note that if the default object access permission was originally defined for a group, with this operation, the permission 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:

  • 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 updating a default object acceess permission. The IRI of the new property must be given in the request body as:
{
  "forProperty":"http://www.knora.org/ontology/00FF/images#titel"
}

Note that if the default object access permission was originally defined for a group, with this operation, the permission will be defined for the given property instead of the group. That means the value of the forGroup will be deleted.

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.