Projectroles REST API Documentation
This document contains the HTTP REST API documentation for the projectroles
app. The provided API enpoints allow project and role operations through
HTTP API calls in addition to the GUI.
API Usage
Usage of the REST API is detailed in this section. These instructions also apply to REST APIs in any other application within SODAR Core and 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.
To enable versioning, add the Accept
header to your request with the
following media type and version syntax. Replace the version number with your
expected version.
Accept: application/vnd.bihealth.sodar-core+json; version=0.9.1
Note
The media type and version for internal SODAR Core apps are by design intended to be different to applications implemented in your Django site. Only use the aforementioned values when calling REST API views in projectroles or other applications installed from the django-sodar-core package.
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 CoreAPIGenericProjectMixin
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.
API Views
- class projectroles.views_api.ProjectListAPIView(**kwargs)[source]
List all projects and categories for which the requesting user has access.
URL:
/project/api/list
Methods:
GET
Returns: List of project details (see
ProjectRetrieveAPIView
)
- 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:
description
: Project description (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
orCATEGORY
)
- 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
orCATEGORY
)parent
: Parent category UUID (string)description
: Projcet 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
: Projcet description (string, optional)readme
: Project readme (string, optional, supports markdown)public_guest_access
: Guest access for all users (boolean)
- 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.
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. e.g. “project delegate”)
- class projectroles.views_api.ProjectInviteListAPIView(**kwargs)[source]
List user invites for a project.
URL:
/project/api/invites/list/{Project.sodar_uuid}
Methods:
GET
Returns: List 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:
app_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:
app_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:
app_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:
app_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]
List users in the system.
URL:
/project/api/users/list
Methods:
GET
Returns:
For each user:
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)
- class projectroles.views_api.CurrentUserRetrieveAPIView(**kwargs)[source]
Return information on the user making the request.
URL:
/project/api/users/current
Methods:
GET
Returns:
For current user:
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)