# elAPI
elAPI is a powerful, extensible API interface to eLabFTW. It supports serving almost all kinds of requests documented in
[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its
arguments.
**Example:**
From [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):
> GET /users/{id}
With elAPI you can do the following:
```sh
$ elapi get users --id <id>
```
## Installation
Support for installing packages with `pip install --user` has been deprecated with the adoption of [PEP 688](https://peps.python.org/pep-0668/) on many systems like [Debian 12](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1030335#5).
We recommend [`pipx`](https://pipx.pypa.io/stable/) for installing elAPI.
```shell
$ pipx install elapi
```
Of course, `pip install --user elapi` might continue to work on some systems.
## Configuration
elAPI needs to be configured first before we can do anything useful with it. elAPI supports a YAML configuration file in
the following locations.
- Current directory: `./elapi.yml`
- User directory: `$HOME/.config/elapi.yml`
- Root directory: `/etc/elapi.yml`
elAPI supports configuration overloading. I.e., a keyword set in root configuration file `/etc/elapi.yml` can be
overriden by setting a different value in user configuration file `$HOME/.config/elapi.yml`. In terms of precedence,
configuration file present in the currently active directory has the highest priority, and configuration in root
directory has the lowest.
The following parameters are currently configurable, with `host` and `api_token` being the required fields. For testing
purposes it would be safe to store everything in the user configuration file.
```yaml
# elAPI configuration
# Saved in `$HOME/.config/elapi.yml`
host: <host API url>
# Example: https://demo.elabftw.net/api/v2/
# Note the host URL ends with the API endpoint
api_token: <token with at least read-access>
# You can generate an API token from eLabFTW user panel -> API keys tab.
export_dir: ~/Downloads/elAPI
unsafe_api_token_warning: yes
```
We can get an overview of detected configurations.
```shell
$ elapi show-config
```
If both `host` and `api_token` are detected, we are good to go!
## Usage
elAPI can be invoked from the command-line.
```shell
$ elapi --help
```
### `GET` requests
We can request an overview of running eLabFTW server.
```shell
$ elapi get info -F yml
# Here -F (or --format) defines the output format
```
We can request a list o all active experiments and export it to a `JSON` file.
```shell
$ elapi get experiments --export ~/Downoads/experiments.json
```
### `POST` requests
We can create a new user by the name 'John Doe'.
```shell
$ elapi post users --id <user id> -d '{"firstname": "John", "lastname": "Doe", "email": "test_test@itnerd.de"}'
```
### `PATCH` requests
We can update an existing user's email address.
```shell
$ elapi patch users --id <user id> -d '{"email": "new_email@itnerd.de"}'
```
`patch` command allows us to make changes to eLabFTW server settings. E.g., we can update the time (in minutes)
after which the authentication cookie will expire.
```shell
$ elapi patch config -d '{"cookie_validity_time": 43200}'
```
We can publish an announcement to all the members.
```shell
$ elapi patch config -d '{"announcement": "Notice: Server will be down tomorrow at midnight due to scheduled maintenance."}'
```
### Bill teams
We can generate invoice for eLabFTW teams.
```shell
$ elapi bill-teams generate-invoice
```
We may just want to have a look at the billing information without generating invoice.
```shell
$ elapi bill-teams info -F yaml
```
We can also export this information as a `YAML` file to the export directory defined in configuration
file (`export_dir`).
```shell
elapi bill-teams info -F yaml --export
```
## Open-source
elAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within
Universität Heidelberg's network. The codebase can still be accessed from [PyPI](https://pypi.org/project/elapi/#files).
If you express interest in having the repository made completely public, or if you have any question, feel free
to [contact us](mailto:elabftw@uni-heidelberg.de).
Raw data
{
"_id": null,
"home_page": "https://www.urz.uni-heidelberg.de/en/service-catalogue/software-and-applications/elabftw",
"name": "elapi",
"maintainer": "Mahadi Xion",
"docs_url": null,
"requires_python": ">=3.9.0,<4.0.0",
"maintainer_email": "mahadi.xion@urz.uni-heidelberg.de",
"keywords": "elabftw,api",
"author": "Alexander Haller",
"author_email": "alexander.haller@urz.uni-heidelberg.de",
"download_url": "https://files.pythonhosted.org/packages/0a/bc/f0720e4cc57569e8f8664806a5dd977390136711048985e7bc109fa6e4cd/elapi-1.0.7.tar.gz",
"platform": null,
"description": "# elAPI\n\nelAPI is a powerful, extensible API interface to eLabFTW. It supports serving almost all kinds of requests documented in\n[eLabFTW API documentation](https://doc.elabftw.net/api/v2/) with ease. elAPI treats eLabFTW API endpoints as its\narguments.\n\n**Example:**\n\nFrom [the documentation](https://doc.elabftw.net/api/v2/#/Users/read-user):\n> GET /users/{id}\n\nWith elAPI you can do the following:\n\n```sh\n$ elapi get users --id <id>\n```\n\n## Installation\n\nSupport for installing packages with `pip install --user` has been deprecated with the adoption of [PEP 688](https://peps.python.org/pep-0668/) on many systems like [Debian 12](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1030335#5).\nWe recommend [`pipx`](https://pipx.pypa.io/stable/) for installing elAPI.\n\n```shell\n$ pipx install elapi\n```\n\nOf course, `pip install --user elapi` might continue to work on some systems.\n\n## Configuration\n\nelAPI needs to be configured first before we can do anything useful with it. elAPI supports a YAML configuration file in\nthe following locations.\n\n- Current directory: `./elapi.yml`\n- User directory: `$HOME/.config/elapi.yml`\n- Root directory: `/etc/elapi.yml`\n\nelAPI supports configuration overloading. I.e., a keyword set in root configuration file `/etc/elapi.yml` can be\noverriden by setting a different value in user configuration file `$HOME/.config/elapi.yml`. In terms of precedence,\nconfiguration file present in the currently active directory has the highest priority, and configuration in root\ndirectory has the lowest.\n\nThe following parameters are currently configurable, with `host` and `api_token` being the required fields. For testing\npurposes it would be safe to store everything in the user configuration file.\n\n```yaml\n# elAPI configuration\n# Saved in `$HOME/.config/elapi.yml`\n\nhost: <host API url>\n# Example: https://demo.elabftw.net/api/v2/\n# Note the host URL ends with the API endpoint\napi_token: <token with at least read-access>\n# You can generate an API token from eLabFTW user panel -> API keys tab.\nexport_dir: ~/Downloads/elAPI\nunsafe_api_token_warning: yes\n```\n\nWe can get an overview of detected configurations.\n\n```shell\n$ elapi show-config\n```\n\nIf both `host` and `api_token` are detected, we are good to go!\n\n## Usage\n\nelAPI can be invoked from the command-line.\n\n```shell\n$ elapi --help \n```\n\n### `GET` requests\n\nWe can request an overview of running eLabFTW server.\n\n```shell\n$ elapi get info -F yml\n# Here -F (or --format) defines the output format\n```\n\nWe can request a list o all active experiments and export it to a `JSON` file.\n\n```shell\n$ elapi get experiments --export ~/Downoads/experiments.json\n```\n\n### `POST` requests\n\nWe can create a new user by the name 'John Doe'.\n\n```shell\n$ elapi post users --id <user id> -d '{\"firstname\": \"John\", \"lastname\": \"Doe\", \"email\": \"test_test@itnerd.de\"}'\n```\n\n### `PATCH` requests\n\nWe can update an existing user's email address.\n\n```shell\n$ elapi patch users --id <user id> -d '{\"email\": \"new_email@itnerd.de\"}'\n```\n\n`patch` command allows us to make changes to eLabFTW server settings. E.g., we can update the time (in minutes)\nafter which the authentication cookie will expire.\n\n```shell\n$ elapi patch config -d '{\"cookie_validity_time\": 43200}'\n```\n\nWe can publish an announcement to all the members.\n\n```shell\n$ elapi patch config -d '{\"announcement\": \"Notice: Server will be down tomorrow at midnight due to scheduled maintenance.\"}'\n```\n\n### Bill teams\n\nWe can generate invoice for eLabFTW teams.\n\n```shell\n$ elapi bill-teams generate-invoice\n```\n\nWe may just want to have a look at the billing information without generating invoice.\n\n```shell\n$ elapi bill-teams info -F yaml\n```\n\nWe can also export this information as a `YAML` file to the export directory defined in configuration\nfile (`export_dir`).\n\n```shell\nelapi bill-teams info -F yaml --export\n```\n\n## Open-source\n\nelAPI is open-source and published under AGPLv3 license. The repository is however hosted internally within\nUniversit\u00e4t Heidelberg's network. The codebase can still be accessed from [PyPI](https://pypi.org/project/elapi/#files).\nIf you express interest in having the repository made completely public, or if you have any question, feel free\nto [contact us](mailto:elabftw@uni-heidelberg.de).",
"bugtrack_url": null,
"license": "AGPL-3.0-only",
"summary": "elAPI is a powerful, extensible API interface to eLabFTW built for the University Computing Centre (URZ, FIRE division) at Universit\u00e4t Heidelberg.",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://www.urz.uni-heidelberg.de/en/service-catalogue/software-and-applications/elabftw"
},
"split_keywords": [
"elabftw",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e2a719faae76c04749fc33dfd471478e94a777bd3bfcc7457a37f6a3ec65800",
"md5": "ba911b1df23dd293911b85d46de0719c",
"sha256": "2a1ed8ecf859aa564e302d87055d641755ba5c619b66f5ee4b3f35e7a7fd320b"
},
"downloads": -1,
"filename": "elapi-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba911b1df23dd293911b85d46de0719c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0,<4.0.0",
"size": 50718,
"upload_time": "2024-01-26T23:56:24",
"upload_time_iso_8601": "2024-01-26T23:56:24.171116Z",
"url": "https://files.pythonhosted.org/packages/8e/2a/719faae76c04749fc33dfd471478e94a777bd3bfcc7457a37f6a3ec65800/elapi-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0abcf0720e4cc57569e8f8664806a5dd977390136711048985e7bc109fa6e4cd",
"md5": "d8a684889582d81e9bf2b666c9caed5d",
"sha256": "e964650cbec81b7df1939959a7fd9509de272c17a32b605cb4863b9c691b0b3f"
},
"downloads": -1,
"filename": "elapi-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "d8a684889582d81e9bf2b666c9caed5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0,<4.0.0",
"size": 42004,
"upload_time": "2024-01-26T23:56:25",
"upload_time_iso_8601": "2024-01-26T23:56:25.794548Z",
"url": "https://files.pythonhosted.org/packages/0a/bc/f0720e4cc57569e8f8664806a5dd977390136711048985e7bc109fa6e4cd/elapi-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 23:56:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "elapi"
}
JSON