Legacy API Docs. These docs are for Virtool 4.3.3.

Subtraction

Find

Find profile subtractions by id (name) or nickname.

GET

/api/subtraction

Parameters

Name	Type	Default	Description
find	string	`null`	subtraction name to filter by
page	integer	1	page number of results to return
per_page	integer	15	number of documents to return per page

Example

GET /api/hmms?find=Arab&per_page=1

Response

Status: 200 OK

{
  "documents": [
    {
      "ready": true,
      "file": {
        "id": "vlekszor-ATgenomeTAIR9.171",
        "name": "ATgenomeTAIR9.171"
      },
      "job": {
        "id": "ritpnbst"
      },
      "id": "Arabidopsis"
    }
  ],
  "total_count": 1,
  "found_count": 1,
  "page_count": 1,
  "per_page": 1,
  "page": 1,
  "host_count": 1,
  "ready_host_count": 1
}

Errors

None

Get

Get the complete representation of a given subtraction.

GET

/api/subtraction/:id

Example

GET /api/subtraction/Arabidopsis

Response

Status: 200 OK

{
  "ready": true,
  "is_host": true,
  "file": {
    "id": "vlekszor-ATgenomeTAIR9.171",
    "name": "ATgenomeTAIR9.171"
  },
  "user": {
    "id": "igboyes"
  },
  "job": {
    "id": "ritpnbst"
  },
  "count": 7,
  "gc": {
    "a": 0.319,
    "t": 0.319,
    "g": 0.18,
    "c": 0.18,
    "n": 0.002
  },
  "linked_samples": [
    {
      "name": "Test 1",
      "id": "htosefxu"
    }
  ],
  "id": "Arabidopsis"
}

Errors

Status	Message	Reason
404	Not found	`sample_id` in URL does not exist

Create

Requires modify_subtraction permission

Create a new subtraction from a file that has previously been uploaded into the file manager.

POST

/api/subtraction

Input

Name	Type	Required	Description
subtraction_id	string	true	a unique name for the host (eg. Arabidopsis)
nickname	string	false	a nickname for the host
file_id	string	true	the unique id of the host FASTA file

Example

POST /api/subtraction

{
  "subtraction_id": "Test 1",
  "nickname": "Foobar",
  "file_id": "djbxvhmy-ATgenomeTAIR9.171"
}

Response

Status: 201 Created

{
  "ready": false,
  "is_host": true,
  "file": {
    "id": "djbxvhmy-ATgenomeTAIR9.171",
    "name": "ATgenomeTAIR9.171"
  },
  "user": {
    "id": "igboyes"
  },
  "job": {
    "id": "rjbszwmm"
  },
  "nickname": "Foobar",
  "id": "Test 1"
}

Errors

Status	Message	Reason
400	File does not exist	file identified by `file_id` does not exist
400	Subtraction id already exists	`id` is already in use by an existing subtraction
403	Not permitted	client does not have the ‘modify_subtraction` permission
422	Invalid input	JSON request body is invalid

Edit

Requires modify_subtraction permission

Change the nickname of an existing subtraction.

PATCH

/api/subtraction/:id

Input

Name	Type	Required	Description
nickname	string	false	a nickname for the host

Example

PATCH /api/subtraction/Arabdidopsis

{
  "nickname": "Thale cress"
}

Response

Status: 200 OK

{
  "ready": true,
  "is_host": true,
  "file": {
    "id": "vlekszor-ATgenomeTAIR9.171",
    "name": "ATgenomeTAIR9.171"
  },
  "user": {
    "id": "igboyes"
  },
  "job": {
    "id": "ritpnbst"
  },
  "count": 7,
  "gc": {
    "a": 0.319,
    "t": 0.319,
    "g": 0.18,
    "c": 0.18,
    "n": 0.002
  },
  "nickname": "Thale cress",
  "id": "Arabidopsis"
}

Errors

Status	Message	Reason
403	Not permitted	client does not have the ‘modify_subtraction` permission
404	Not found	subtraction does not exist
422	Invalid input	JSON request body is invalid

Remove

Requires modify_subtraction permission

Remove an existing subtraction

DELETE

/api/subtraction/:id

Example

DELETE /api/subtraction/Test%201

Response

Status: 204 No content

Errors

Status	Message	Reason
403	Not permitted	client does not have the ‘modify_subtraction` permission
404	Not found	subtraction does not exist
`409`	Has linked samples	subtraction is in use by one or more sample and cannot be removed