Sample Sheets API

The REST API for sample sheet operations is described in this document.

Versioning

Media Type

application/vnd.bihealth.sodar.samplesheets+json

Current Version

1.2

Accepted Versions

1.0, 1.1, 1.2

Header Example

Accept: application/vnd.bihealth.sodar.samplesheets+json; version=x.y

API Views

Sample Sheet Management

class samplesheets.views_api.InvestigationRetrieveAPIView(**kwargs)

Retrieve metadata of an investigation with its studies and assays.

This view can be used to e.g. retrieve assay UUIDs for landing zone operations.

URL: /samplesheets/api/investigation/retrieve/{Project.sodar_uuid}

Methods: GET

Returns:

• archive_name: Original archive name if imported from a zip (string)

• comments: Investigation comments (dict)

• description: Investigation description (string)

• file_name: Investigation file name (string)

• identifier: Locally unique investigation identifier (string)

• irods_status: Whether iRODS collections for the investigation have been created (boolean)

• parser_version: Version of altamISA used in importing (string)

• project: Project UUID (string)

• sodar_uuid: Investigation UUID (string)

• studies: Study and assay information (dict, using study UUID as key)

• title: Investigation title (string)

class samplesheets.views_api.SheetImportAPIView(**kwargs)

Upload sample sheet as separate ISA-Tab TSV files or a zip archive. Will replace existing sheets if valid.

The request should be in format of multipart/form-data. Content type for each file must be provided.

URL: /samplesheets/api/import/{Project.sodar_uuid}

Methods: POST

Returns:

• detail: Detail of project success (string)

• sodar_warnings: SODAR import issue warnings (list of srings, optional)

class samplesheets.views_api.SheetISAExportAPIView(**kwargs)

Export sample sheets as ISA-Tab TSV files, either packed in a zip archive or wrapped in a JSON structure.

URL for zip export: /samplesheets/api/export/zip/{Project.sodar_uuid}

URL for JSON export: /samplesheets/api/export/json/{Project.sodar_uuid}

Methods: GET

iRODS Data Objects and Collections

class samplesheets.views_api.IrodsCollsCreateAPIView(**kwargs)

Create iRODS collections for a project.

Returns 503 if the project is currently locked by another operation.

URL: /samplesheets/api/irods/collections/create/{Project.sodar_uuid}

Methods: POST

Returns:

• path: Full iRODS path to the root of created collections (string)

class samplesheets.views_api.SampleDataFileExistsAPIView(**kwargs)

Return status of data object existing in SODAR iRODS by checksum. Includes all projects in search regardless of user permissions.

The checksum is expected as MD5 or SHA256, depending on which is set as the hash scheme for the SODAR and iRODS servers.

If SHEETS_API_FILE_EXISTS_RESTRICT is set True on the server, this view is only accessible by users who have a guest role or above in at least one category or project.

URL: /samplesheets/api/file/exists

Methods: GET

Parameters:

• checksum: MD5 or SHA256 checksum as hex (string)

Returns:

• detail: String

• status: Boolean

class samplesheets.views_api.ProjectIrodsFileListAPIView(**kwargs)

Return a list of files in the project sample data repository. Optionally also returns collections.

Supports optional pagination for listing by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

URL: /samplesheets/api/file/list/{Project.sodar_uuid}

Methods: GET

Parameters:

• include_colls: Include collections in list (boolean, optional)

• page: Page number for paginated results (int, optional)

Returns:

List of iRODS items (list of dicts). Each dict contains:

• name: Name of data object or collection

• type: Item type (obj for data object, coll for collection)

• path: Full iRODS path for item

• size: Size in bytes (only for data objects)

• modify_time: Datetime of last modification (YYYY-MM-DDThh:mm:ssZ, only for data objects)

• checksum: Checksum (only for data objects)

Version Changes:

• 1.1: Add checksum field to return data

• 1.1: Add page parameter for optional pagination

• 1.2: Add include_colls parameter

iRODS Access Tickets

class samplesheets.views_api.IrodsAccessTicketRetrieveAPIView(**kwargs)

Retrieve an iRODS access ticket for a project.

URL: /samplesheets/api/irods/ticket/retrieve/{IrodsAccessTicket.sodar_uuid}

Methods: GET

Returns

• path: Full iRODS path (string)

• label: Text label for ticket (string, optional)

• ticket: Ticket string for accessing the path (string)

• assay: Assay UUID (string)

• study: Study UUID (string)

• date_created: Creation datetime (YYYY-MM-DDThh:mm:ssZ)

• date_expires: Expiry datetime (YYYY-MM-DDThh:mm:ssZ or null)

• allowed_hosts: Allowed hosts for ticket access (list)

• user: UUID of user who created the request (string)

• is_active: Whether the request is currently active (boolean)

• sodar_uuid: IrodsAccessTicket UUID (string)

Version Changes:

• 1.1: Add allowed_hosts field

class samplesheets.views_api.IrodsAccessTicketListAPIView(**kwargs)

List iRODS access tickets for a project.

Supports optional pagination for listing by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

URL: /samplesheets/api/irods/ticket/list/{Project.sodar_uuid}

Methods: GET

Query parameters:

• active (boolean, optional, default=false)

• page: Page number for paginated results (int, optional)

Returns: List of ticket dicts, see IrodsAccessTicketRetrieveAPIView

class samplesheets.views_api.IrodsAccessTicketCreateAPIView(**kwargs)

Create an iRODS access ticket for collection or data object in a project.

URL: /samplesheets/api/irods/ticket/create/{Project.sodar_uuid}

Methods: POST

Parameters:

• path: Full iRODS path to collection or data object (string)

• label: Text label for ticket (string, optional)

• date_expires: Expiration date (YYYY-MM-DDThh:mm:ssZ, optional)

• allowed_hosts: Allowed hosts for ticket access (list, optional)

Returns: Ticket dict, see IrodsAccessTicketRetrieveAPIView

Version Changes:

• 1.1: Add allowed_hosts field

class samplesheets.views_api.IrodsAccessTicketUpdateAPIView(**kwargs)

Update an iRODS access ticket for a project.

URL: /samplesheets/api/irods/ticket/update/{IrodsAccessTicket.sodar_uuid}

Methods: PUT, PATCH

Parameters:

• label: Label (string)

• date_expires: Expiration date (YYYY-MM-DDThh:mm:ssZ, optional)

• allowed_hosts: Allowed hosts for ticket access (list, optional)

Returns: Ticket dict, see IrodsAccessTicketRetrieveAPIView

Version Changes:

• 1.1: Add allowed_hosts field

class samplesheets.views_api.IrodsAccessTicketDestroyAPIView(**kwargs)

Delete an iRODS access ticket.

URL: /samplesheets/api/irods/ticket/delete/{IrodsAccessTicket.sodar_uuid}

Methods: DELETE

iRODS Data Requests

class samplesheets.views_api.IrodsDataRequestRetrieveAPIView(**kwargs)

Retrieve a iRODS data request.

URL: /samplesheets/api/irods/request/retrieve/{IrodsDataRequest.sodar_uuid}

Methods: GET

Returns:

• project: Project UUID (string)

• action: Request action (string)

• path: iRODS path to object or collection (string)

• target_path: Target path (string, currently unused)

• user: UUID of user initiating request (string)

• status: Request status (string)

• status_info: Request status info (string)

• description: Request description (string)

• date_created: Request creation date (datetime)

• sodar_uuid: Request UUID (string)

class samplesheets.views_api.IrodsDataRequestListAPIView(**kwargs)

List the iRODS data requests for a project.

If the requesting user is an owner, delegate or superuser, the view lists all requests with the status of ACTIVE or FAILED. If called as a contributor, returns the user’s own requests regardless of the state.

Supports optional pagination for listing by providing the page query string. This will return results in the Django Rest Framework PageNumberPagination format.

URL: /samplesheets/api/irods/requests/{Project.sodar_uuid}

Methods: GET

Query parameters:

• page: Page number for paginated results (int, optional)

Returns: List of iRODS data requests (list of dicts)

class samplesheets.views_api.IrodsDataRequestCreateAPIView

Create an iRODS delete request for a project.

The request must point to a collection or data object within the sample data repository of the project. The user making the request must have the role of contributor or above in the project.

URL: /samplesheets/api/irods/request/create/{Project.sodar_uuid}

Methods: POST

Parameters:

• path: iRODS path to object or collection (string)

• description: Request description (string, optional)

class samplesheets.views_api.IrodsDataRequestUpdateAPIView

Update an iRODS data request for a project.

URL: /samplesheets/api/irods/request/update/{IrodsDataRequest.sodar_uuid}

Methods: PUT, PATCH

Parameters:

• path: iRODS path to object or collection (string)

• description: Request description

class samplesheets.views_api.IrodsDataRequestDestroyAPIView

Delete an iRODS data request object.

This action only deletes the request object and is equvalent to cencelling the request. No associated iRODS collections or data objects will be deleted.

URL: /samplesheets/api/irods/request/delete/{IrodsDataRequest.sodar_uuid}

Methods: DELETE

class samplesheets.views_api.IrodsDataRequestAcceptAPIView

Accept an iRODS data request for a project.

Accepting will delete the iRODS collection or data object targeted by the request. This action can not be undone.

Returns 503 if the project is currently locked by another operation.

URL: /samplesheets/api/irods/request/accept/{IrodsDataRequest.sodar_uuid}

Methods: POST

class samplesheets.views_api.IrodsDataRequestRejectAPIView

Reject an iRODS data request for a project.

This action will set the request status as rejected and keep the targeted iRODS collection or data object intact.

URL: /samplesheets/api/irods/request/reject/{IrodsDataRequest.sodar_uuid}

Methods: POST

Version Changes

v1.2

• ProjectIrodsFileListAPIView

  • Add include_colls parameter

v1.1

• IrodsAccessTicketRetrieveAPIView

  • Add allowed_hosts field

• IrodsAccessTicketCreateAPIView

  • Add allowed_hosts field

• IrodsAccessTicketUpdateAPIView

  • Add allowed_hosts field

• ProjectIrodsFileListAPIView

  • Add checksum field to return data

  • Add page parameter for optional pagination