Legacy API Docs. These docs are for Virtool 4.4.0.

Groups

List

List all existing user groups.

GET
/api/groups

Example

GET /api/groups

Response

Status: 200 OK

[
  {
    "permissions": {
      "cancel_job": true,
      "create_ref": false,
      "create_sample": true,
      "modify_hmm": false,
      "modify_subtraction": false,
      "remove_file": false,
      "remove_job": true,
      "upload_file": true
    },
    "id": "technicians"
  }
]

Errors

None

Get

Get the complete representation of a single user group.

GET
/api/groups/:id

Example

GET /api/groups/technicians

Response

Status: 200 OK

{
  "permissions": {
    "cancel_job": true,
    "create_ref": false,
    "create_sample": true,
    "modify_hmm": false,
    "modify_subtraction": false,
    "remove_file": false,
    "remove_job": true,
    "upload_file": true
  },
  "id": "technicians"
}

Errors

StatusMessageReason
404Not foundgroup does not exist

Create

Role Administrator

Create a new group. New groups have no permissions. Requestors must be administrators.

POST
/api/groups

Input

NameTypeDescription
group_idstringa unique id and display name for the group

Example

POST /api/groups

{
  "group_id": "research"
}

Response

Status: 201 Created

{
  "permissions": {
    "cancel_job": false,
    "create_ref": false,
    "create_sample": false,
    "modify_hmm": false,
    "modify_subtraction": false,
    "remove_file": false,
    "remove_job": false,
    "upload_file": false
  },
  "id": "research"
}

Errors

StatusMessageReason
400Group already existsthe provided group_id already exists
403Not permittedclient is not an administrator
422Invalid inputJSON request body is invalid

Edit

Role Administrator

Update the permissions of an existing group. Unset permissions will retain their previous setting.

PATCH
/api/groups/:id

Input

NameTypeDescription
permissionsbooleana permission update comprising an object keyed by permissions with boolean values

Example

PATCH /api/groups/research

{
  "permissions": {
    "create_ref": true
  }
}

Response

Status: 200 OK

{
  "permissions": {
    "cancel_job": false,
    "create_ref": true,
    "create_sample": false,
    "modify_hmm": false,
    "modify_subtraction": false,
    "remove_file": false,
    "remove_job": false,
    "upload_file": false
  },
  "id": "research"
}

Errors

StatusMessageReason
403Not permittedclient is not an administrator
404Not foundgroup does not exist
422Invalid inputJSON request body is invalid

Remove

Role Administrator

Remove an existing group.

DELETE
/api/groups/:id

Example

DELETE /api/groups/foobar

Response

Status: 204 No Content

 

Errors

StatusMessageReason
403Not permittedclient is not an administrator
404Not foundgroup does not exist