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. Beware: this package is only published for developing purpose, DON'T USE IT ON A 7.2 PRODUCTION SERVER.

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

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

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.

You 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	[email protected]

** The linuxmuster community consits 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.