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

2.0

Accepted Versions

1.0, 1.1, 2.0

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_access: Read-only access for all users (role name as string or None)

  • 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:

  • 2.0

    • Replace roles field user serializer with user UUID

    • Replace public_guest_access field with public_access

  • 1.1

    • Add children field

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

Create a project or a category.

If setting public read-only access for users, provide role name (“project guest” or “project viewer”) or None for no access.

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_access: Public read-only access for all users (string or None)

  • owner: User UUID of the project owner (string)

Version Changes:

  • 2.0

    • Replace public_guest_access field with public_access

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.

If setting public read-only access for users, provide role name (“project guest” or “project viewer”) or None for no access.

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_access: Public read-only access for all users (string or None)

  • 2.0

    • Replace public_guest_access field with public_access

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

Version Changes:

  • 2.0: Replace issuer field user serializer with user UUID

class projectroles.views_api.ProjectInviteRetrieveAPIView(**kwargs)[source]

Retrieve a project invite.

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

Methods: GET

Returns:

  • date_created: Creation datetime string (YYYY-MM-DDThh:mm:ssZ)

  • date_expire: Expiry datetime string (YYYY-MM-DDThh:mm:ssZ)

  • message: Optional invite message (string)

  • issuer: UUID of issuing user (string)

  • email: Email of invited user (string)

  • project: Project UUID (string)

  • role: Role for invided user (string, e.g. “project contributor”)

  • sodar_uuid: Invite UUID (string)

Version Changes:

  • 2.0: Add view

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)

Returns:

  • plugin_name: Name of app plugin for the setting (string)

  • project: Project UUID or None

  • user: User UUID or None

  • name: Setting name (string)

  • type: Setting type (string)

  • value: Setting value

  • user_modifiable: Modifiable by user (boolean)

Version Changes:

  • 2.0: Replace user field user serializer with user UUID

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)

Returns:

  • plugin_name: Name of app plugin for the setting (string)

  • project: None

  • user: User UUID

  • name: Setting name (string)

  • type: Setting type (string)

  • value: Setting value

  • user_modifiable: Modifiable by user (boolean)

Version Changes:

  • 2.0: Replace user field user serializer with user UUID

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

v2.0

  • ProjectInviteListAPIView

    • Replace issuer field user serializer with user UUID

  • ProjectInviteRetrieveAPIView

    • Add view

  • ProjectRetrieveAPIView

    • Replace roles field user serializer with user UUID

    • Replace public_guest_access field with public_access

  • ProjectCreateAPIView

    • Replace public_guest_access field with public_access

  • ProjectUpdateAPIView

    • Replace public_guest_access field with public_access

  • ProjectSettingRetrieveAPIView

    • Replace user field user serializer with user UUID

  • UserSettingRetrieveAPIView

    • Replace user field user serializer with user UUID

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