• Rlabkey API
• Python API
• Security

What is Rlabkey?

It is an API which makes it easy for R users to load live data from a LabKey Server into the R environment.

Features of Rlabkey:

• user must have appropriate permissions
• user credentials are obtained from a separate location than the running R program
• records stored on a LabKey Server can be:
  
  • read
  • inserted
  • updated
  • deleted
• it uses HTTP requests to communicate with a LabKey Server

How do I set credentials to access LabKey data from my local machine?

Please, check the FAQ Security for details about setting credentials.

How do I use the API?

Install the "Rlabkey" package in the host from which one needs to access the remote LabKey data using the following command from the R console:

> install.packages("Rlabkey")  

Load the "Rlabkey" library at the start of every R script or in the R console using the following command:

> library(Rlabkey)  

Example of accessing the content of a list, using the method "labkey.selectRows()" in the R console:

> rows <- labkey.selectRows(baseUrl="https://labkey.scicore.unibas.ch/labkey", folderPath="Public datasets/Iris dataset",schemaName="lists", queryName="Iris")

Where can I get more documentation about Rlabkey?

• List of available methods in the Rlabkey package: Rlabkey documentation (pdf)
• Use the R command "RlabkeyUsersGuide()" to download the "Rlabkey Users Guide".
• LabKey documentation in Rlabkey Package.

What is LabKey's Python API?

It is an API which allows to query, insert and update data on a LabKey Server from Python, plus programmatically update wikis and post to message boards.

How do I set credentials to access LabKey data from my local machine?

Please, check the FAQ Security for details about setting credentials.

How do I install the API?

Install the library in the host from which you need to access the remote LabKey data using the following command from the shell:
$ pip install labkey

More information in the GitHub's project labkey-api-python and in the Python Package Index PyPI labkey.

How do I use the API?

Example of accessing the content of the list "Iris" in schema "lists" of project "Public datasets / Iris dataset", using the method "select_rows()" in the Python console:

>>> from labkey.api_wrapper import APIWrapper
>>> server_context = APIWrapper('labkey-collab.scicore.unibas.ch', 'Public datasets/Iris dataset', '', use_ssl = True)
>>> result = server_context.query.select_rows('lists','Iris')
>>> print(result['rows'][0]['SepalLength'])
5.4

More information in the GitHub's project labkey-api-python.

Where can I get more examples of the API's usage?

In the LabKey GitHub repositories:

• labKey-api-python
• samples/python

Toy example: test_api_filter.py

How do I create a .netrc or _netrc file?

Create a file named ".netrc" ("_netrc" on Windows) in your home directory.
This file must include the following 3 lines:

machine <remote-instance-of-labkey-server>
login <user-email>
password <user-password>

E.g.:

machine labkey.scicore.unibas.ch
login eva.pujadas@unibas.ch
password xxxxx

The row "machine" denotes either the IP-address or the name of the server running the Labkey instance (the example could contain the IP-address of the "labkey.scicore.unibas.ch" server instead).
Note that you must not include "https://" or the port number (e.g. "127.0.0.1:8080") here.
The row "login" describes a valid user name for the Labkey instance. Rlabkey can access every content that the particular user has been granted permission for.
The row "password" contains the valid password of the above user for the Labkey instance.

More details in LabKey documentation Create a .netrc or _netrc file.

How do I secure the credentials file?

Two proposals:

(1) Set file permissions

(2) Encrypt

For more security, encrypt the file using PGP, for example.

Encrypt with:
$ gpg -c .netrc
Be sure to delete the original file after creating the encrypted version. Otherwise, there is no protection.
Be sure to remember keys or passphrases. There is no recovery.

And decrypt with:
$ gpg .netrc.gpg
There is no need to give the passphrase when decrypting in the same environment where the file was encrypted.

How is the credentials file accessed?

LabKey APIs will automatically access the credentials stored in the credential file, given the file is located in the right place, that is, in your home directory.

Can you give more details on Windows?

How should I create the _netrc file?

Use a text editor (e.g. TextWrangler) to create the "_netrc" file and save it as "_netrc" (without file extension such as ".txt" or the like).

Where should I store the _netrc file?

The "_netrc" file should be located in the home-directory of the computer that accesses Labkey via the APIs.
This requires you to create an environment variable containing the path to your home-directory. For more details on environment variables see this page.

What is an API key?

An API key is a long, randomly generated token that provides an alternative authentication credential for use with APIs.
API keys have security benefits over passwords:

• they are used to authenticate to a sever, avoiding the use and storage of a LabKey password on the client machine.
• they are tied to a specific server.
• they can be configured to expire.
• they can be revoked.

But since a valid API key provides complete access to your data and actions, it should be kept secret.

The API key can be used in several ways:

• specifying the key in the ".netrc" (or "_netrc") file. E.g.:
  
  machine labkey.scicore.unibas.ch
login apikey
password apikey|the_rest_of_the_long_api_key_copied
  
  
• providing it to API functions.
• using it with external clients that support Basic authentication.

More details can be found in the LabKey documentation API Keys.

How can I create an API key?

• Select the menu " --> API Keys" on the top right-hand side of the page.
• Click the button "Generate API Key".
• To grab the key, click the button "Copy to Clipboard". The button will read "Copied!" when the copy has completed.
• Finalize by clicking the button "Done".

How to disable validation of self-signed SSL certificates?

If you are using a self-signed certificate, and connecting via HTTPS on a Mac or Linux machine, you may see issues as labkey attempts unsuccessfully to validate that certificate.
Validation can be disabled in the following way:

In Rlabkey

To bypass the peer and host verification steps, add the following to your script:

> labkey.setCurlOptions(ssl_verifyhost=FALSE,ssl_verifypeer=FALSE)

More information in LabKey documentation Troubleshooting Rlabkey Connections.

In Python

To bypass the SSL verification step, add the parameter "use_ssl" with value "False" when creating the server context. E.g.:

server_context = create_server_context('labkey.scicore.unibas.ch', 'Public datasets/Iris dataset', 'labkey', use_ssl = False)