# Modulplaner OpenAPI

OpenAPI documentation of the modulplaner API


## Optional endpoints

This OpenAPI spec contains some "optional" endpoints. This is down to the fact, that the
module planner can be used on a static website, or also be integrated into a server that
is connected to a database.

When the Modulplaner is set to be hosted on a static site, the endpoints marked with
`[OPTIONAL:*]` can not be reached.

- `[OPTIONAL:Storage]`: Storage endpoints for the users/students
- `[OPTIONAL:Management]`: management endpoints for administrators


## Authentication

The defined authentication can be exchanged for any valid authentication. The spec only
represents which endpoints should require authentication when implementing a server.


## Definitions

- `Module`:  A specific unit or component of a broader course of study. It focuses on a
  particular topic or subject area within a course. Modules are usually part of a larger
  framework, and a course will consist of multiple modules.
- `Course`: Refers to the entire program of study leading to a degree. It encompasses
  multiple modules that are structured over the duration of the (bachelors) program.
- `Term`: Refers to any academic period, but it is often associated with systems that
  divide the academic year into two or more periods.
- `Lecture`: A single session, where the *lecture* of a *Module* is held.
- `Lecture series`: An entire series over a *term* of *lectures* (of a single class).
- `Class`: A subset of students, that attend a *Lecture*/*Lecture Series*.
- `Lecturer`: The person teaching the students.
- `Student`: The person, who should be learning about new stuff.
- `Revision`: Revision of something that has been previously published.
- `Block (lecture)`: A lecture, that is held over a short timespan (shorter than a
  term), where the students visit daily.

- `First name`: The first/given name of a person
- `Surname`: The Surname/Family name (different to last name in some cases!)


### Do not use these terms

- `Semester`: This term is too limiting compared to `Term`, as it always refers to 6
  months. Some schools will use different lengths for their terms.
- `Degree`: We should use the term `Course`, as the degree is what you receive when
  completing a `Course`.
- `Teacher`: Use `Lecturer` instead, as this is the common term used by universities.
- `Version`: If a `revision` is meant instead.


## Types used

The numeric fields have an additional `format` tag assigned.

### Unsigned

- `u…`: Unsigned … bit
- `u8`: Unsigned 8 bit (0 - 255)
- `u16`: Unsigned 16 bit (0 - 65'535)


### Signed

- `i…`: Signed … bit
- `i8`: Signed 8 bit (-128 - 127)
- `i16`: Signed 16 bit (-32'768 - 32'767)


### Floating

- `f32`: 32 bit floating point number
- `f64`: 64 bit floating point number