Landing Zones API

The REST API for landing zone operations is described in this document.

Versioning

Media Type

application/vnd.bihealth.sodar.landingzones+json

Current Version

1.1

Accepted Versions

1.0, 1.1

Header Example

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

API Views

class landingzones.views_api.ZoneListAPIView(**kwargs)[source]

List the landing zones in a project.

If the user has rights to view all zones, every zone in the project will be listed. Otherwise only their own zones appear in the list. Also returns finished (meaning moved or deleted) zones if the “finished” parameter is set.

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

URL: /landingzones/api/list/{Project.sodar_uuid}?finished={integer}

Methods: GET

Parameters:

  • finished: Include finished zones if 1 (integer)

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

Returns: List of landing zone details (see ZoneRetrieveAPIView)

class landingzones.views_api.ZoneRetrieveAPIView(**kwargs)[source]

Retrieve the details of a landing zone.

URL: /landingzones/api/retrieve/{LandingZone.sodar_uuid}

Methods: GET

Returns:

  • assay: Assay UUID (string)

  • coll_creation: Collection creation mode (string)

  • config_data: Data for special configuration (dict)

  • configuration: Special configuration name (string)

  • date_modified: Last modification date of the zone (string)

  • description: Landing zone description (string)

  • irods_path: Full iRODS path to the landing zone (string)

  • project: Project UUID (string)

  • sodar_uuid: Landing zone UUID (string)

  • status: Current status of the landing zone (string)

  • status_info: Detailed description of the landing zone status (string)

  • status_locked: Whether write access to the zone is currently locked (boolean)

  • title: Full title of the created landing zone (string)

  • user: UUID of user who owns the zone (string)

  • user_message: Message displayed to users on successful moving of zone (string)

Version Changes:

  • 1.1: Add coll_creation field

class landingzones.views_api.ZoneCreateAPIView(**kwargs)[source]

Create a landing zone.

Returns 503 if an investigation for the project is not found or project iRODS collections have not been created.

URL: /landingzones/api/create/{Project.sodar_uuid}

Methods: POST

Parameters:

  • assay: Assay UUID (string)

  • config_data: Data for special configuration (dict, optional)

  • configuration: Special configuration (string, optional)

  • description: Landing zone description (string, optional)

  • user_message: Message displayed to users on successful moving of zone (string, optional)

  • title: Suffix for the zone title (string, optional)

  • create_colls: Create expected collections (boolean, optional)

  • restrict_colls: Restrict access to created collections (boolean, optional)

Returns: Landing zone details (see ZoneRetrieveAPIView)

class landingzones.views_api.ZoneUpdateAPIView(**kwargs)[source]

Update a landing zone description and user message.

URL: /landingzones/api/update/{LandingZone.sodar_uuid}

Methods: PATCH, PUT

Parameters:

  • description: Landing zone description (string, optional)

  • user_message: Message displayed to users on successful moving of zone (string, optional)

Returns: Landing zone details (see ZoneRetrieveAPIView)

class landingzones.views_api.ZoneSubmitDeleteAPIView(**kwargs)[source]

Initiate landing zone deletion.

Initiates an asynchronous operation. The zone status can be queried using ZoneRetrieveAPIView with the returned sodar_uuid.

URL: /landingzones/api/submit/delete/{LandingZone.sodar_uuid}

Methods: POST

class landingzones.views_api.ZoneSubmitMoveAPIView(**kwargs)[source]

Initiate landing zone validation and/or moving.

Initiates an asynchronous operation. The zone status can be queried using ZoneRetrieveAPIView with the returned sodar_uuid.

For validating data without moving it to the sample repository, this view should be called with submit/validate.

Returns 503 if the project is currently locked by another operation or if the concurrent validation limit for the project has been reached.

URL for Validation: /landingzones/api/submit/validate/{LandingZone.sodar_uuid}

URL for Moving: /landingzones/api/submit/move/{LandingZone.sodar_uuid}

Methods: POST

class landingzones.views_api.ZoneSettingsRetrieveAPIView(**kwargs)[source]

Retrieve currently active settings related to landing zone creation for a specific project. The following settings are returned:

LANDINGZONES_DISABLE_FOR_USERS

Disable landing zone creation for non-superusers (boolean)

LANDINGZONES_TRIGGER_ENABLE

Enable landing zone move triggering by uploaded file (boolean)

LANDINGZONES_TRIGGER_FILE

File name for landing zone file triggering (string)

LANDINGZONES_ZONE_CREATE_LIMIT

Zone creation limit per project (integer or None)

LANDINGZONES_ZONE_VALIDATE_LIMIT

Zone validation limit per project (integer)

file_name_prohibit

Prohibited file name suffixes for zones in this project (list)

URL: /landingzones/api/settings/retrieve/{Project.sodar_uuid}

Methods: GET

Returns:

  • settings: Setting names and values (dict)

Version Changes:

  • 1.1: Add view

class landingzones.views_api.ZoneIrodsFileListAPIView(**kwargs)[source]

Return a list of files in a landing zone. Optionally also returns collections and MD5/SHA256 checksum files.

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

URL: /landingzones/api/file/list/{LandingZone.sodar_uuid}

Methods: GET

Parameters:

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

  • include_checksum: Include checksum files in list (boolean, optional, default=False)

  • 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 view

Version Changes

v1.1

  • ZoneRetrieveAPIView

    • Add coll_creation field

  • ZoneIrodsFileListAPIView

    • Add view

  • ZoneSettingsRetrieveAPIView

    • Add view