robinlh / hinkskalle-api

Talking to Hinkskalle

Hinkskalle API

Talking to Hinkskalle made easy

Use me to

• list available downloads
• download data
• upload data

Getting Started

hinkskalle-api provides

• a small library with a thin wrapper over the JSON API
• a CLI (hinkli: short for hink-cli, get it?)

Installation

You will need python3 and pip. Then you can run:

pip3 install git+https://github.com/csf-ngs/hinkskalle-api

Command Line Interface

Get a list of available commands and options:

hinkli --help

Your first step should be logging in:

# non-VBCF.NGS users get your own instance!
hinkli --base https://singularity.ngs.vbcf.ac.at/ login
# answer prompt for username and password

The registry and token should now be stored in ~/.hink_api.yml and available for further use.

Discovering & Downloading Data

Your most likely use case will be downloading data provided via Hinkskalle.

# shows available collections of containers
hinkli list-collections
hinkli list-containers [collection]
hinkli list-downloads [collection]/[container]
hinkli pull [collection]/[container]:[tag]
# username is optional, but can be provided, too:
hinkli list-collections test.hase
hinkli list-containers test.hase/[collection]
# etc

Basic structure:

• A Collection holds a bunch of containers (topic, type, ...)
• Containers hold tagged data
• Each tag points to some data (some tags point to the same data)

If Hinkskalle shows you these downloads in your container test.hase/example/FAQ4711:

- filename: bunch_of_reads.fastq.gz
  size: 41.5 MB
  tags: basecalled,20210621
- filename: rawdata.tar.gz
  size: 41.5 TB
  tags: raw

You can use these commands to download:

# either one fetches bunch_of_reads.fastq
hinkli pull example/FAQ4711:basecalled
hinkli pull example/FAQ4711:20210621
# fetches rawdata.tar.gz
hinkli pull example/FAQ4711:raw

Hinkli will even check the sha256 checksum for you!

API

Not documented - use at your own risk!

from hinkskalle_api import HinkApi
api = HinkApi()
collections = api.list_collections()
# etc

Configuration

By default, hinkli reads its config from ~/.hink_api.yml. This file should look like this:

hink_api_base: https://singularity.ngs.vbcf.ac.at
hink_api_key: your_super_secret_token

You can use these env variables to override:

• HINK_API_BASE
• HINK_API_KEY
• HINK_API_CFG - to look for the config file in a different location

Development

You can regenerate the models from the Hinkskalle swagger/openapi definition:

pip3 install git+https://ngs.vbcf.ac.at/repo/software/swagspotta.git
# from pkg.ngs.vbcf.ac.at production:
share/create_models.sh
# from your local hinkskalle dev server:
share/create_models.sh http://localhost:7660/swagger