SFB/TRR 173 SPIN+X

API

Using the API a way to read or write data to eLabFTW from an external program (like a Python script).

For instance, instead of using a web browser to access the web interface and create an experiment, you make a call to the API saying “hey, create an experiment for me”, and the API will reply with the ID of the newly created experiment.

Installation and usage are nicely described in the elabapy documentation.

For a quick start, you can follow these steps to read and write your first data into elabFTW:

  • In order to reach our instance of elabFTW you need to create an API-Key. You can do that in elabFTW by navigating to the user panel and clicking on "API Key". There you can assign a name and permissions. After creation, the key will be displayedonly once. After that, there is no way to receive this key again. Therefore make sure to store this key in a safe way.

  • With a valid key and a proper installation of elabapy, you can start to write your python script. Besides importing elabapy itself it should start with creating an instance of elabapy's Manager class, which takes an endpoint you should define first. In the case of the group Aeschlimann, you have to use https://elab.uni-kl.de/api/v1/. After all, your script should look something like this.

# API of ElabFTW

import elabapy

# Import Error class to catch HTTP Errors

from requests.exceptions import HTTPError

keyfile = open("key.txt", "r")

apikey = keyfile.read()

# Do not change that!

endpoint = "https://elab.uni-kl.de/api/v1/"

# With this manager you gain access to ElabFTW if your key is correct

manager = elabapy.Manager(endpoint=endpoint, token=apikey)

  • You should now be able to access elabFTW. You can use the commands described in the elabapy documentation. An example of these will be added soon in Gitlab. One important thing to mention is that each experiment and each database item has it's own ID. You can use this ID to e.g. read out the data which is stored in an experiment or an item. You can see this ID in the URL of the corresponding object like it's shown below.

For new experiments or items, you create over the API, the corresponding ID will be returned as a String. If you want to update an experiment over time, it would be a good idea to store these in some kind of database or file.

If you want to create new database items, you have to input the right "category id" in order to create the right item type. For example, if you use the category id 3, you will create a new sample item. You can look at the table below to choose the right category id.

Zum Seitenanfang