Skip to content

Hands-on: CLI - 101 Getting Started

  • 15 min
  • Moderate
Overview

The goal of this hands-on tutorial is to get the LabID Python Client installed on your machine and be able to retrieve some basic information from LabID.

  • Install the package from Gitlab
  • Setup credentials
  • Searching and listing entities

Walkthrough

Prerequisites

We assume that you are familiar with conda or with Python Virtual Environments.

There are two ways to install the client. Either installing the development version - by cloning the git repository (git needs to be installed on your computer) - or downloading it from the Gitlab PyPI. For this training, we will install the development version.

The client we will install can be found at LabID Python Client repository. You can login with your EMBL Credentials.

Step 1. Set up a conda environment

Use conda to compartment software on your computer

We advise creating a conda environment to avoid version mismatch and make sure the proper version of python is used.

  • On your computer, create a conda virtual environment with Python3
    conda create -n labid-cli python=3 jq=1.6
  • Activate the virtual environment
    conda activate labid-cli

Step 2. Clone the LabID Python Client

  • Clone the repo
    git clone https://gitlab.com/lab-integrated-data/labid-cli.git
  • Move to the labid-cli directory
    cd labid-cli
  • Install the client
    pip install -e .
Summarized 
conda create -n labid-cli python=3 jq=1.6
conda activate labid-cli
git clone https://gitlab.com/lab-integrated-data/labid-cli.git
cd labid-cli
pip install -e .
Alternatively, install the client from the internal PyPI

Step2.1 Acquire a gitlab token

On the Gitlab instance at EMBL:

  • Go to Account -> Preferences
  • From the User Settings menu, click Access Tokens
  • Add Token name: LabID Python Client
  • Select the scope: read_api
  • Hit the button: Create personal access token
  • Make sure to copy the newly generated token

Create a Gitlab token
Create a Gitlab token. (1) User preferences; (2) Access tokens; (3) Token name; (4) Token permission scope.

Step2.2

  • In a shell with the conda environment activated (see step 1.), execute the following command after replacing <your_personal_token> with your token: 
    pip install LabID-client --extra-index-url https://__token__:<your_personal_token>@git.embl.de/api/v4/projects/3470/packages/pypi/simple

Step 3. Configure the client

The client needs to be configured to communicate with the LabID.
Here we will configure our client to communicate with the training instance.

  • Execute the following command first, 
    labid config setup

It will first prompt for the url of the training instance, paste https://labid-demo.embl.de then enter.
Next step is entering the username, you can use any username in the range trainee1...trainee100, again press enter.
Then the password 123456 and press enter.
Finally the unix group, which can be any value for now.

Trainee credentials

The client is now setup with the training credentials.

Every action done with the Python client will be authenticated as this training user.

Step 4. Retrieving data

We can now start querying the training instance.
Try the following commands and see what result you get.

  • labid get item --id <uuid> (Replace <uuid> with any of the IDs from the search result or take one from the UI)
  • labid get instruments --type MICROSCOPE | jq
Format of the retrieved information

The information is obtained in the JSON format. This is the base format for API responses. Using jq the data is transformed in a readable and parsable way. The information retrieved is similar to that retrieved by the UI client. In fact, our UI is solely retrieving and sending data from and to the API!

As such, the python client or any other client one would write, can retrieve the same and possibly more data from the API.

To see what endpoints the UI uses, open up the network tab of your browser and inspect the requests. You can repeat these requests, by using a 'manual' REST client like Insomnia.

Write operations are currently not available

Currently, the client only does GET operations, meaning readonly. Write operation are technically possible and we will start supporting them in future releases.

Please contact us when using the API for the first time so that a test/development instance is setup for you. Our API will protect for most invalid data, but as our UI has been our sole consumer/producer of API calls, we may be missing some validations.

Do not test against production! We will find you

In the next hands on we will look at different functionality that is exclusive to the CLI like a ArrayExpress like export and linking files.