Projectroles REST API Documentation

This document contains the HTTP REST API documentation for the projectroles app. For general information on REST API usage in SODAR Core, see REST API Overview.

Projectroles REST API Versioning

Media Type: application/vnd.bihealth.sodar-core.projectroles+json
Current Version: 1.1
Accepted Versions: 1.0, 1.1
Header Example: Accept: application/vnd.bihealth.sodar-core.projectroles+json; version=x.y

Projectroles REST API Views

class projectroles.views_api.ProjectListAPIView(**kwargs)[source]

List all projects and categories for which the requesting user has access.

Supports optional pagination by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

URL: /project/api/list

Methods: GET

Parameters:

page: Page number for paginated results (int, optional)

Returns:

List of Project objects (see ProjectRetrieveAPIView). For project finder role, only lists title and UUID of projects.

class projectroles.views_api.ProjectRetrieveAPIView(**kwargs)[source]

Retrieve a project or category by its UUID.

URL: /project/api/retrieve/{Project.sodar_uuid}

Methods: GET

Returns:

archive: Project archival status (boolean)
children: Category children (list of UUIDs, only returned for categories)
description: Project description (string)
full_title: Full project title with parent categories (string)
parent: Parent category UUID (string or null)
readme: Project readme (string, supports markdown)
public_guest_access: Guest access for all users (boolean)
roles: Project role assignments (dict, assignment UUID as key)
sodar_uuid: Project UUID (string)
title: Project title (string)
type: Project type (string, options: PROJECT or CATEGORY)

Version Changes:

1.1: Add children field

class projectroles.views_api.ProjectCreateAPIView(**kwargs)[source]

Create a project or a category.

URL: /project/api/create

Methods: POST

Parameters:

title: Project title (string)
type: Project type (string, options: PROJECT or CATEGORY)
parent: Parent category UUID (string)
description: Project description (string, optional)
readme: Project readme (string, optional, supports markdown)
public_guest_access: Guest access for all users (boolean)
owner: User UUID of the project owner (string)

class projectroles.views_api.ProjectUpdateAPIView(**kwargs)[source]

Update the metadata of a project or a category.

Note that the project owner can not be updated here. Instead, use the dedicated API view RoleAssignmentOwnerTransferAPIView.

The project type can not be updated once a project has been created. The parameter is still required for non-partial updates via the PUT method.

URL: /project/api/update/{Project.sodar_uuid}

Methods: PUT, PATCH

Parameters:

title: Project title (string)
type: Project type (string, can not be modified)
parent: Parent category UUID (string)
description: Project description (string, optional)
readme: Project readme (string, optional, supports markdown)
public_guest_access: Guest access for all users (boolean)

class projectroles.views_api.ProjectDestroyAPIView(**kwargs)[source]

Destroy a project and all associated data.

Deletion is prohibited if called on a category with children or a project with non-revoked remote projects.

NOTE: This operation can not be undone!

URL: /project/api/destroy/{Project.sodar_uuid}

Methods: DELETE

Version Changes:

1.1: Add view

class projectroles.views_api.RoleAssignmentCreateAPIView(**kwargs)[source]

Create a role assignment in a project.

URL: /project/api/roles/create/{Project.sodar_uuid}

Methods: POST

Parameters:

role: Desired role for user (string, e.g. “project contributor”)
user: User UUID (string)

class projectroles.views_api.RoleAssignmentUpdateAPIView(**kwargs)[source]

Update the role assignment for a user in a project.

The user can not be changed in this API view.

URL: /project/api/roles/update/{RoleAssignment.sodar_uuid}

Methods: PUT, PATCH

Parameters:

role: Desired role for user (string, e.g. “project contributor”)
user: User UUID (string)

class projectroles.views_api.RoleAssignmentDestroyAPIView(**kwargs)[source]

Destroy a role assignment.

The owner role can not be destroyed using this view.

URL: /project/api/roles/destroy/{RoleAssignment.sodar_uuid}

Methods: DELETE

class projectroles.views_api.RoleAssignmentOwnerTransferAPIView(**kwargs)[source]

Trensfer project ownership to another user with a role in the project. Reassign a different role to the previous owner.

The new owner must already have a role assigned in the project.

NOTE: Barring any inherited role, if no value is given for old_owner_role, the old owner’s access to the project will be removed.

URL: /project/api/roles/owner-transfer/{Project.sodar_uuid}

Methods: POST

Parameters:

new_owner: User name of new owner (string)
old_owner_role: Role for old owner (string or None, e.g. “project delegate”)

Version Changes:

1.1: Allow empty value for old_owner_role

class projectroles.views_api.ProjectInviteListAPIView(**kwargs)[source]

List user invites for a project.

Supports optional pagination by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

URL: /project/api/invites/list/{Project.sodar_uuid}

Methods: GET

Parameters:

page: Page number for paginated results (int, optional)

Returns: List or paginated dict of project invite details

class projectroles.views_api.ProjectInviteCreateAPIView(**kwargs)[source]

Create a project invite.

URL: /project/api/invites/create/{Project.sodar_uuid}

Methods: POST

Parameters:

email: User email (string)
role: Desired role for user (string, e.g. “project contributor”)

class projectroles.views_api.ProjectInviteRevokeAPIView(**kwargs)[source]

Revoke a project invite.

URL: /project/api/invites/revoke/{ProjectInvite.sodar_uuid}

Methods: POST

class projectroles.views_api.ProjectInviteResendAPIView(**kwargs)[source]

Resend email for a project invite.

URL: /project/api/invites/resend/{ProjectInvite.sodar_uuid}

Methods: POST

class projectroles.views_api.ProjectSettingRetrieveAPIView(**kwargs)[source]

API view for retrieving an app setting with the PROJECT or PROJECT_USER scope.

URL: project/api/settings/retrieve/{Project.sodar_uuid}

Methods: GET

Parameters:

plugin_name: Name of app plugin for the setting, use “projectroles” for projectroles settings (string)
setting_name: Setting name (string)
user: User UUID for a PROJECT_USER setting (string or None, optional)

class projectroles.views_api.ProjectSettingSetAPIView(**kwargs)[source]

API view for setting the value of an app setting with the PROJECT or PROJECT_USER scope.

URL: project/api/settings/set/{Project.sodar_uuid}

Methods: POST

Parameters:

plugin_name: Name of app plugin for the setting, use “projectroles” for projectroles settings (string)
setting_name: Setting name (string)
value: Setting value (string, may contain JSON for JSON settings)
user: User UUID for a PROJECT_USER setting (string or None, optional)

class projectroles.views_api.UserSettingRetrieveAPIView(**kwargs)[source]

API view for retrieving an app setting with the USER scope.

URL: project/api/settings/retrieve/user

Methods: GET

Parameters:

plugin_name: Name of app plugin for the setting, use “projectroles” for projectroles settings (string)
setting_name: Setting name (string)

class projectroles.views_api.UserSettingSetAPIView(**kwargs)[source]

API view for setting the value of an app setting with the USER scope. Only allows the user to set the value of their own settings.

URL: project/api/settings/set/user

Methods: POST

Parameters:

plugin_name: Name of app plugin for the setting, use “projectroles” for projectroles settings (string)
setting_name: Setting name (string)
value: Setting value (string, may contain JSON for JSON settings)

class projectroles.views_api.UserListAPIView(**kwargs)[source]

Return a list of all users on the site. Excludes system users, unless called with superuser access.

Supports optional pagination by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

If PROJECTROLES_API_USER_DETAIL_RESTRICT is set True on the server, this view is only accessible by users who have a contributor role or above in at least one category or project.

URL: /project/api/users/list

Methods: GET

Parameters:

include_system_users: Include system users if True (bool, optional)
page: Page number for paginated results (int, optional)

Returns: List or paginated dict of serializers users (see CurrentUserRetrieveAPIView)

Version Changes:

1.1: Add include_system_users parameter

class projectroles.views_api.UserRetrieveAPIView(**kwargs)[source]

Return user details for user with the given UUID.

If PROJECTROLES_API_USER_DETAIL_RESTRICT is set True on the server, this view is only accessible by users who have a finder role or above in at least one category or project.

URL: /project/api/users/{SODARUser.sodar_uuid}

Methods: GET

Returns:

additional_emails: Additional verified email addresses for user (list of strings)
auth_type: User authentication type (string)
email: Email address of the user (string)
is_superuser: Superuser status (boolean)
name: Full name of the user (string)
sodar_uuid: User UUID (string)
username: Username of the user (string)

Version Changes:

1.1: Add view

class projectroles.views_api.CurrentUserRetrieveAPIView(**kwargs)[source]

Return user details for user performing the request.

URL: /project/api/users/current

Methods: GET

Returns:

User details, see UserRetrieveAPIView.

Version Changes:

1.1: Add auth_type field

Projectroles REST API Version Changes

v1.1

ProjectDestroyAPIView
- Add view
ProjectRetrieveAPIView
- Add children field
RoleAssignmentOwnerTransferAPIView
- Allow empty value for old_owner_role
UserListAPIView
- Add include_system_users parameter
UserRetrieveAPIView
- Add view
CurrentUserRetrieveAPIView
- Add auth_type field