Projectroles REST API Documentation

This document contains the HTTP REST API documentation for the projectroles app. The provided API endpoints allow project and role operations through HTTP API calls in addition to the GUI.

API Usage

General information on usage of the REST APIs in SODAR Core is detailed in this section. These instructions also apply to REST APIs in any other application within SODAR Core. They are recommended as guidelines for API development in your SODAR Core based Django site.

Authentication

The API supports authentication through Knox authentication tokens as well as logging in using your SODAR username and password. Tokens are the recommended method for security purposes.

For token access, first retrieve your token using the Tokens App. Add the token in the Authorization header of your HTTP request as follows:

Authorization: token 90c2483172515bc8f6d52fd608e5031db3fcdc06d5a83b24bec1688f39b72bcd

Versioning

The SODAR Core REST API uses accept header versioning. While specifying the desired API version in your HTTP requests is optional, it is strongly recommended. This ensures you will get the appropriate return data and avoid running into unexpected incompatibility issues.

From SODAR Core v1.0 onwards, each application is expected to use its own media type and version numbering. To enable versioning, add the Accept header to your request with the app’s respective media type and version number. Example for the projectroles API:

Accept: application/vnd.bihealth.sodar-core.projectroles+json; version=x.y

Model Access and Permissions

Objects in SODAR Core API views are accessed through their sodar_uuid field. This is strongly recommended for views implemented in your Django site as well, as using a field such as pk may reveal internal database details to users as well as be incompatible if e.g. mirroring roles between multiple SODAR Core sites.

In the remainder of this document and other REST API documentation, “UUID” refers to the sodar_uuid field of each model unless otherwise noted.

For permissions the API uses the same rules which are in effect in the SODAR Core GUI. That means you need to have appropriate project access for each operation.

Project Type Restriction

IF you want to explicitly restrict access for your API view to a specific project type, you can set the project_type attribute of your class to either PROJECT_TYPE_PROJECT or PROJECT_TYPE_CATEGORY as defined in SODAR_CONSTANTS. A request to the view using the wrong project type will result in a 403 Not Authorized response, with the reason displayed in the detail view.

This works with any API view using SODARAPIProjectPermission as its permission class, which includes SODARAPIBaseProjectMixin and SODARAPIGenericProjectMixin. An example is shown below.

from rest_framework.generics import RetrieveAPIView
from projectroles.models import SODAR_CONSTANTS
from projectroles.views_api import SODARAPIGenericProjectMixin

class YourAPIView(SODARAPIGenericProjectMixin, RetrieveAPIView):
    # ...
    project_type = SODAR_CONSTANTS['PROJECT_TYPE_PROJECT']

Return Data

The return data for each request will be a JSON document unless otherwise specified.

If return data is not specified in the documentation of an API view, it will return the appropriate HTTP status code along with an optional detail JSON field upon a successfully processed request.

For creation views, the sodar_uuid of the created object is returned along with other object fields.

Pagination

From SODAR Core V1.0 onwards, list views support pagination unless otherwise specified. Pagination can be enabled by providing the ?page=x query string in the API request. This will change the return data into a paginated format. Example:

{
    'count' 170,
    'next': 'api/url?page=3',
    'previous': 'api/url?page=1',
    'results': [
        # ...
    ]
}

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