REST API Command List

Structure of the URI

http://example.com:8080/flow/api/v1

Authentication

The username and access token must be supplied, unless the request is made in an authenticated session.

The access token can be generated from the settings page or using the public key included in the PartekFlow-REST.zip as described in REST API

Projects

/projects

POST, PUT

Creates or modifies a project. Returns data for the specified project.

GET

Returns data for the specified project.

DELETE

Deletes the specified project.

Required parameters

Parameter

Type

Description

project OR

project_id

string

integer

The name of the project.

The ID of the project.

Optional parameters

Parameter	Type	Description
owner	string	Sets the project owner
name	string	Sets the project name
description	string	Sets the project description
collaborator	string	If this parameter is specified, then “role” must also be specified. If the role parameter is “remove” then the specified collaborator is removed from the project, otherwise role must be a valid project role (Collaborator or Viewer).
my_output_folder	string	Sets the project output folder for the user making the request
output_folder	string	Sets the project output folder for all collaborators the user making the request has permission to affect

Responses

200: application/json

The name, id, description, owner, user roles, output folders, disk usage, time of last modification, and data of the project.

400: Returned if the project parameter is missing.

403: Returned on a PUT request if a project with the specified name already exists.

Returned on a GET request if the user does not have permission to view the specified project.

404: Returned on a GET request if no project with the specified name exists

/projects/list

POST, PUT, GET

Returns the list of visible projects on the server.

Optional parameters

The following filters can be applied to the list:

Parameter	Type	Description
project_ids	string	Retrieve specific projects. IDs joined by ,
project_id	integer	Retrieve a single project by ID
project	string	Retrieve a single project by name
sample	string	List projects that contain a sample with the specified name.
file_name	string	List projects that contain a file matching the specified sub-string.
user_id	integer	List projects for which the specified user is a member.
user_name	string	List projects for which the specified user is a member.

By default this returns each project visible to the user making the request.

Responses

200: application/json

The name, id, description, owner, user roles, output folders, disk usage, time of last modification, and data of each project.

/projects/import

POST

Creates a project from the specified zip.

Required parameters

Parameter	Type	Description
filename	string	The name of the file being uploaded.
file	string	The file content

OR

Parameter	Type	Description
url	string	A URL corresponding to a valid Flow project.

OR

Parameter	Type	Description
filepath	string	A file on the server.

Responses

200: application/json

The name, id, description, owner, and data of the project

500: If an error occurs importing the project

/projects/export

POST, GET

Exports the specified project(s) to a zip.

Required parameters

Parameter	Type	Description
projectIds	string	Project IDs separated by “,” specify "all" to export all projects

Optional parameters

Parameter	Type	Description
includeLibraryFiles	boolean	If true, library files will be included in the project zip. Default: false
outputFolder	string	The path to a folder on the server. By default the exported project is sent to the client. If this parameter is specified then one .zip file for each project will be written into this folder.

Responses

200 application/zip

A zip file containing the project content.

/projects/output_folders

GET

List the output folders for visible projects.

Optional parameters

Parameter	Type	Description
project_ids	string	Retrieve specific projects. IDs joined by ,
project_id	integer	Retrieve a single project by ID
project	string	Retrieve a single project by name
sample	string	List projects that contain a sample with the specified name.
file_name	string	List projects that contain a file matching the specified sub-string.
user_id	integer	List projects for which the specified user is a member.
user_name	string	List projects for which the specified user is a member.

Responses

200: application/json

The full path for each projects output directory. If no user_id or user_name is specified then the directory returned will be for the user making the request.

/projects/files

GET

List each file associated with a project.

Optional parameters

Parameter	Type	Description
project_ids	string	Retrieve specific projects. IDs joined by ,
project_id	integer	Retrieve a single project by ID
project	string	Retrieve a single project by name
sample	string	List projects that contain a sample with the specified name.
file_name	string	List projects that contain a file matching the specified sub-string.
user_id	integer	List projects for which the specified user is a member.
user_name	string	List projects for which the specified user is a member.

Responses

200: application/json

The list of files

/projects/folders

GET

List the each folder which has one or more files associated with a project.

Optional parameters

Parameter	Type	Description
project_ids	string	Retrieve specific projects. IDs joined by ,
project_id	integer	Retrieve a single project by ID
project	string	Retrieve a single project by name
sample	string	List projects that contain a sample with the specified name.
file_name	string	List projects that contain a file matching the specified sub-string.
user_id	integer	List projects for which the specified user is a member.
user_name	string	List projects for which the specified user is a member.

Responses

200: application/json

The list of folders

/projects/samples

GET

List the samples associated with projects.

Optional parameters

Parameter	Type	Description
project_ids	string	Retrieve specific projects. IDs joined by ,
project_id	integer	Retrieve a single project by ID
project	string	Retrieve a single project by name
sample	string	List projects that contain a sample with the specified name.
file_name	string	List projects that contain a file matching the specified sub-string.
user_id	integer	List projects for which the specified user is a member.
user_name	string	List projects for which the specified user is a member.

Responses

200: application/json

The ID and name for each project that pass the specified filter. The ID and name for each sample in each project.

Samples

/samples

POST, PUT

Creates a sample. Returns data for the specified sample.

GET

Returns data for the specified sample.

Required parameters

Parameter

Type

Description

sample_id

OR sample

integer

string

The ID of the sample.

The name of the sample.

project

string

The name of the sample’s project.

Optional parameters

Parameter

Type

Description

attribute OR

vocabulary

string

If both an attribute and term are specified, then the specified categorical term is applied to the sample

term OR value

string

Parameter	Type	Description
numeric_attribute	string	If both an and value are specified, then the specified numeric value is applied to the sample
value	string

Responses

200: application/json

The name, id, files, and attributes of the sample

400: Returned if the sample or project parameters are missing.

403: Returned if the user does not have permission to create samples in the project

404: Returned if there is no project with the given id or if a sample with the specified name can not be found

Example

http://example.com:8080/flow/api/v1/samples?project=My%20Project&sample=Sample1

{

"name": "Sample1",
"id": "0",
"files": [

"FastqFileDataType: 14138"

],
"attributes": {
   "Type": [
     "Normal"
   ],
   "Pair": [
     "1"
   ]
}
}

/samples/list

POST, GET

Returns a list of samples in the specified project.

Required parameters

Parameter	Type	Description
project	string	The name of the project.

Responses

200: application/json

The name, id, files, and attributes of each sample in the project

/samples/attributes

GET

Returns the attributes of samples

Required parameters

Parameter

Type

Description

project_Id OR

project

integer

string

The ID of the project.

The name of the project.

Optional parameters

Parameter

Type

Description

sample_Id OR

sample OR

sample_name

integer

string

The ID of the sample.

The name of the sample.

Responses

200: application/json

The name, id, and attributes of each sample in the project

Data

/data

POST,PUT

Uploads a file for analysis.

Supported files: unaligned reads, alignments, detected variants.

Required parameters

Parameter

Type

Description

filename OR filepath

string

The name of the file being uploaded.

The location of the file on the server.

file

binary

The file content. \[If filename is specifi\]

project OR

project_id

string

integer

The name of the project to add the sample to.

The ID of the project to add the sample to.

Optional parameters

Parameter

Type

Description

sample_id OR

sample OR

new_sample

integer

string

The id of the sample to add file to.

The name of the sample to add the file to.
The name of the sample to add the file to. If a sample with this name already exists then characters will be added to disambiguate the new sample.

Without this parameter a new sample will be created.

owner

string

The username of the user that should be the owner of the data. The data will count against this user’s quota, if one is configured. By default, the owner will be the user account that uploads the data.

upload_folder

string

If the file is uploaded through the servlet it will be put in this directory, if the owner has permission to access it.

Responses

200: application/json

id The ID of the data node for the file’s content type.

400: Returned if the specified file is not of a recognized type.

403: Returned if the user does not have permission to create samples in the project

404: Returned if there is no project with the given id

Library Files

/library_files

POST, PUT

Uploads and manages a library file

GET

Returns data about a specified library file

Required parameters

For upload:

Parameter	Type	Description
file	binary	The file content.
file_type	string	The type of library file. The list of available library file types is returned by /library_files/types
assembly	string	The assembly of the library file

Optional parameters

Parameter	Type	Description
species	string	The species of the library file. This is looked up based on the assembly, and the assembly is used as the species if the assembly is not associated with any species.

Responses

200: application/json

The id of the imported library file

400: Returned if any required parameters are missing

Required parameters

Parameter	Type	Description
file_type	string	The type of library file. The list of available library file types is returned by /library_files/types
assembly	string	The assembly of the library file

Responses

200: application/json

The id of the specified resource

400: Returned if any required parameters are missing

404: Returned if no library file is managed for the specified library file and assembly

/library_files/types

POST, GET

Returns the list of library file types that the server can managed

Responses

200: application/json

The list of manageable library file types: Genome sequence, cytoBand.txt, Annotation model, Bowtie Index, Bowtie Colorspace Index, Bowtie2 Index, Tmap Index, BWA Index, SHRiMP2 Index, SHRiMP2 Colorspace Index, GSNAP Index, STAR Index, STAR 2.4.1d Index, Isaac2 Index, GSNAP 2015-12-31 (v8) Index, Variant database, Variant frequencies, Gene Set, SnpEff, VEP, Kraken Database

/library_files/list

POST, GET

Returns information about library files managed by the server

Optional parameters

Parameter	Type	Description
assembly	string	The assembly
annotation_model OR annotationModel	string	The annotation model
file_type OR fileType	string	The type of library file. The list of available library file types is returned by /library_files/types
description	string	Filter the library file list to those that match this description.
id	integer	The ID of the library file

Responses

200: application/json

The assembly, annotation model, filetype, description and id for each library file that passes the filters.

/library_files/files

POST, GET

Returns the paths of library files managed by the server

Optional parameters

Parameter

Type

Description

assembly

string

The assembly

file_type OR

fileType

string

The type of library file. The list of available library file types is returned by /library_files/types

Responses

200: application/json

The assembly, filetype, and list of files for each library file that passes the filters.

Pipelines

/pipelines

POST, GET

Downloads a pipeline specification.

Required parameters

Parameter	Type	Description
pipeline	string	The name of the pipeline

Responses

200: application/json

The pipeline definition.

400: Returned if the pipeline parameter is missing

403: Returned if the user does not have permission to view the pipeline.

404: Returned if the specified pipeline can not be found.

/pipelines/list

POST, GET

Returns a list of pipelines managed by the server

Responses

200: application/json

The name, description, file, deletable status, creation date, and creator for each pipeline.

Example

http://example.com:8080/flow/api/v1/pipelines/list

[

{
   "name": "My Pipeline",
   "description": "",
   "protocolFile": {
     "path": "\/home\/flow\/.partekflow\/partek_db\/protocol\/P20150629140508365_0.json"
   },
   "deletable": true,
   "creationDate": "1472850094644",
   "creator": {
     "arg$1": {
       "section": "Pipelines",
       "date": 1435604708365,
       "user": "",
       "userID": 0,
       "name": "My Pipeline",
       "description": ""
     }
   }
}

]

/pipelines/input

POST, GET

Returns the required inputs for a specified pipeline

Required parameters

Parameter	Type	Description
pipeline	string	The name of the pipeline
project	string	The project that the pipeline will run in

Optional parameters

Parameter	Type	Default	Description
data	string	Unaligned reads	The data node that the pipeline will run on, as returned by the /projects interface.

Responses

200: application/json

A list of tasks and their required inputs.

403: Returned if the user does not have permission to view the pipeline.

404: Returned if the specified pipeline can not be found.

Example

http://example.com:8080/flow/api/v1/pipelines/inputs?project=My%20Project&pipeline=My%20Pipeline

{

"BowtieTask": [
"ebwt_reference"
],
"SamtoolsTask": [
"referenceFasta"
]
}

/pipelines/run

POST, GET

Runs the pipeline

Required parameters

Parameter	Type	Description
pipeline	string	The name of the pipeline to run.
project	string	The name of the project to run the pipeline in
inputs	integers	The ids of the resources, in the order returned by the /pipeline/inputs interface. The ids of library files are returned by the /library_files interface.

Optional parameters

Parameter	Type	Default	Description
data	string	Unaligned reads	The data node to run the pipeline on, as returned by the /projects interface.

Responses

200: application/json

pipeline_queued: [the list of queued task IDs]

If there are missing inputs then the list of required inputs will be returned.

400: Returned if a required parameter is missing.

403: Returned if the user does not have permission to run tasks on the specified data node.

404: Returned if the specified project, data, or pipeline can not be found.

500: Returned if there is an error queueing the pipeline

Example

http://example.com:8080/flow/api/v1/pipelines/run?project=My%20Project&pipeline=My%Project&inputs=1,2

pipeline_queued: 1805,1806

Queue

/queue

POST, GET

Downloads summary information about the queue

Optional parameters

Parameter	Type	Description
project_filter	string	Only return tasks in this project
user_filter	string	Only return tasks run by this user

Responses

200: application/json

running: the number of tasks currently running commands

waiting: the total number of tasks queued, but not running

waitingForDiskSpace: tasks that won’t run until hard disk space is made available.

waitingForProject: tasks that can’t run because of the project limit

waitingForResources: tasks that require more resources (such as memory) to run

waitingForUpstreamTask: tasks for which the input is currently unavailable

permanentlyStalled: tasks that are waitingForDiskSpace or for which there is no worker with sufficient capacity to run

hasPendingCommands: true if there are commands which can run if more resources are made available

403: Returned if the user does not have permission to view the queue.

404: Returned if the specified project can not be found.

Example

http://example.com:8080/flow/api/v1/queue

{

"running": 1,
"waiting": 4,
"waitingForDiskSpace": 0,
"waitingForProject": 0,
"waitingForResources": 3,
"waitingForUpstreamTask": 1,
"permanentlyStalled": 0,

"hasPendingCommands":"true"

}

/queue/downloads

POST, GET

Returns the count of files being downloaded to the server from servlets and tasks.

Responses

200: application/json

servletDownloads, taskDownloads

/queue/commands

POST, GET

Returns the count of commands that are pending and running.

Responses

200: application/json

pending, running

/queue/tasks

POST, GET

Downloads information about the queued tasks

Optional parameters

Parameter	Type	Description
project OR project_name	string	The name of a project
project_id	integer	The ID of a project
user_name	string	The username of a user
user_id	integer	The ID of a user
status	string	The task status: Pending, Waiting, Running, Done, Canceled, Failed

Responses

200: application/json

id, task, runStatus, progress, submitted, started, end

403: Returned if the user does not have permission to view the queue.

404: Returned if the specified project can not be found.

/queue/cancel

POST, GET

Cancels the specified task(s)

Optional parameters

Parameter	Type	Description
project OR project_name	string	The name of a project
project_id	integer	The ID of a project
user_name	string	The username of a user
user_id	integer	The ID of a user
status	string	The task status: Pending, Waiting, Running, Done, Canceled, Failed

Responses

200: application/json

The number of tasks canceled

403: Returned if the user does not have permission to view the queue.

404: Returned if the specified project can not be found.

Example

http://example.com:8080/flow/api/v1/queue/tasks

[
{
   "id": 2590,
   "task": "Post-alignment QA\/QC",
   "runStatus": "Pending",
   "progress": 0,
   "submitted": "21 Oct 2016, 03:33 PM CDT",
   "started": "NA",
   "end": "NA"
},
{
   "id": 2589,
   "task": "TMAP - 5.0.0",
   "runStatus": "Running",
   "progress": 5,
   "submitted": "21 Oct 2016, 03:33 PM CDT",
   "started": "21 Oct 2016, 03:33 PM CDT",
   "end": "21 Oct 2016, 03:38 PM CDT"
}
]

Users

/users

POST, PUT

Add and configure a specified user

Optional parameters

One of the following may be specified:

Parameter	Type	Description
user_name	string	The username of the user. If the user does not exist it will be created.
user_id	integer	The ID of the user

If neither is specified, then the user specified by the username parameter (or the logged-in user) will be used

Parameter	Type	Description
distinguished_name	string	When creating a new user, this parameter specifies the LDAP distinguished name.
user_password	string	When creating a new user, this parameter specifies their initial Flow password. If this parameter is absent and this is not an LDAP user then the user will receive an email with a link to set their initial password.
email	string	The user’s email address. When creating a new user, this parameter is required.
display_name	string	The name that other users will see
enabled	boolean	Whether the user is able to log in.
admin	boolean	Whether the user has the admin role. The system requires at least one admin account.
private_directory	string	If present, the directory will be created and the user will be given permission to use it.
quota	integer	The size of the user’s quota (in gigabytes) or “none” to remove any quota
notify_when_tasks_finish	boolean	Whether the user will receive an email when a task they have queued completes
notify_when_added_to_project	boolean	Whether the user will receive an email when they are added as a collaborator or viewer to a project
decimal_precison	integer	How many digits to show after the decimal point for numeric values in tables

Responses

200: application/json

id, name, displayName, isOnline, tasksInQueue, diskQuota, diskUsage (in gigabytes)

400: Returned if the user_name or user_id parameter is specified, but does not identify a valid user.

GET

Returns information about a specified user

Optional parameters

One of the following may be specified:

Parameter	Type	Description
user_name	string	The username of the user
user_id	integer	The ID of the user

if neither is specified, then the user specified by the username parameter (or the logged-in user) will be used

Responses

200: application/json

id, name, displayName, isOnline, tasksInQueue, diskQuota, diskUsage (in gigabytes)

400: Returned if the user_name or user_id parameter is specified, but does not identify a valid user.

Example

http://example.com:8080/flow/api/v1/users?user_id=0

[
{
   "id": 0,
   "name": "admin",
   "displayName": "Administrator",
   "isOnline": true,
   "tasksInQueue": 1,
   "diskUsage": 83516042096
}
]

/users/list

GET

Returns information about all users on the system

Responses

200: application/json

id, name, displayName, isOnline, tasksInQueue, diskQuota, diskUsage (in gigabytes)

Tasks

/tasks

POST, GET

Returns a summary of tasks run on the server

Optional parameters

These parameters filter the task list

Parameter	Type	Description
id	integer	A specific task ID
user_name OR user_id	string integer	The name of a user The ID of a user
project OR project_id	string integer	The name of a project The ID of a project
status	string	A task status (e.g. Done, Running, Pending)
task	string	The type of task (e.g. Bowtie)

Responses

200: application/json

id, user, project, status, task

Commands

/commands

GET

Returns a summary of commands running on the server.

Optional parameters

These parameters filter the command list

Parameter	Type	Description
task	integer	The ID of a task
workerIdentifier	string	The ID of a worker
successful	boolean	Did the command finish successfully?
commandLine	string	Search for sub-strings within the commandline.

Responses

200: application/json

commandId, workerIdentifier, cpu, memoryMbs, startTimeMillis, runTimeMillis, successful, commandLine

Licensing

/license

POST, GET

Returns a summary of the available licenses.

Optional parameters

These parameters filter the command list

Parameter	Type	Description
feature	string	Query for a specific license feature

Responses

200: application/json

accounts, isNodeLocked, isConcurrent, expiration, version

Workers

/workers

POST, GET

Returns a summary of workers on the server.

Responses

200: application/json

systemIdentifier, workerIdentifier, isInternal, name, commandResourceUsageLimit, systemResourceUsageLimit, timeAtThisStatusInSeconds, responsive, taskIds

/workers/remote

POST, GET

Returns a summary of remote workers on the server.

Responses

200: application/json

systemIdentifier, workerIdentifier, isInternal, name, commandResourceUsageLimit, systemResourceUsageLimit, timeAtThisStatusInSeconds, responsive, taskIds

/workers/internal

POST, GET

Returns a summary of the internal worker.

Responses

200: application/json

systemIdentifier, workerIdentifier, isInternal, name, commandResourceUsageLimit, systemResourceUsageLimit, timeAtThisStatusInSeconds, responsive, taskIds

System

POST, PUT

Configure system parameters

GET

Returns system parameters

Optional parameters

These parameters filter the command list

Parameter	Type	Description
log_level	string	Sets the current log-level: ALL, TRACE, DEBUG, INFO, WARN, ERROR, OFF
page_load_log_threshold	integer	If specified and greater than 0 a warning will be written to logs/page_load.log whenever a page-load takes longer than this value (in seconds)

Responses

200: application/json

setPageLoadThresholdInSeconds

Additional Assistance

If you need additional assistance, please visit our support page to submit a help ticket or find phone numbers for regional support.

Your Rating:

Results:

1

rates

Partek Flow Documentation

Page tree

REST API Command List

Structure of the URI

Authentication

Projects

/projects

/projects/list

/projects/import

/projects/export

/projects/output_folders

/projects/files

/projects/folders

/projects/samples

Samples

/samples

/samples/list

/samples/attributes

Data

/data

Library Files

/library_files

/library_files/types

/library_files/list

/library_files/files

Pipelines

/pipelines

/pipelines/list

/pipelines/input

/pipelines/run

Queue

/queue

/queue/downloads

/queue/commands

/queue/tasks

/queue/cancel

Users

/users

/users/list

Tasks

/tasks

Commands

/commands

Licensing

/license

Workers

/workers

/workers/remote

/workers/internal

System

Additional Assistance