linuxmuster-api

Linuxmuster API is the main evolution for the next linuxmuster.net's server, version 8. Based on the wonderful FastAPI, it will give the possibility to let other software to interact with the data and tools provided by the linuxmuster.net's server.

Installation

Simply install the package linumxuster-api7 from our deb repository.

After the installation, the uvicorn server should start automatically ans listen on port 8001. You can manage it via systemctl:

systemctl start linuxmuster-api
systemctl stop linuxmuster-api

It is then necessary to configure your firewall in order to restrict the access to linuxmuster-api, please read the paragraph "Security" bellow.

Configuration

Some configurations options are stored in /etc/linuxmuster/api/config.yml:

• uvicorn:
  • port: 8001 (default)
  • host: 0.0.0.0 (default)
  • ssl_certfile: /etc/linuxmuster/api/lmnapi.pem (self-signed, default)
  • ssl_keyfile: /etc/linuxmuster/api/lmnapi.pem (self-signed, default)
  • log_level: info (default)
  • log_config: /etc/linuxmuster/api/log_conf.yaml (default, configuration of the logging Python module)
• secret: secret key generated by the install process in order to generate JWT tokens, keep it secret.
• cors: (some examples)
  • allow_origins:
    • http://example.com
    • https://localhost:8001
  • allow_credentials: true
  • allow_methods:
    • GET
    • POST
  • allow_headers: ['*']

First steps

FastApi provides two complete documentations to learn the API:

• https://SERVER:8001/docs : Swagger UI, you can see all endpoints and interact directly with all of these
• https://SERVER:8001/redoc: Full documentation about all endpoints.

Security

Firewall

Warning

In his default configuration, linuxmuster-api listen on port 8001. Since the API can provide sensitive information, it's very important to restrict the access to this port to only the clients or machines who need it.

Authentication

The endpoints are per role and per user secured. Each request MUST provide a valid JWT (JSON Web Token) in the header (key X-Api-Key) to get the data.

An user can get a valid JWT token by sending username and password via Basic auth at the endpoint https://SERVER:8001/v1/auth.

First request

You are yet so far to launch your first request, just send a GET request with your JWT to https://SERVER:8001/v1/schoolclasses and you will get a whole list of all schoolclasses on the server ! Have fun with it :)

Maintainance Details

Linuxmuster.net official	✅ YES
Community support	✅ YES*
Actively developed	✅ YES
Maintainer organisation	Linuxmuster.net / Netzint GmbH
Primary maintainer	@kiarn

• The linuxmuster community consists of people who are nice and happy to help. They are not directly involved in the development though, and might not be able to help in any case.

Development

This project is pretty young and there's many room for improvement:

• add all necessary endpoint to provide enough flexibility,
• correctly handle all type of errors (500, 401, 404, ...),
• and many more ... any help is welcome.