diff --git a/REST-API.md b/REST-API.md new file mode 100644 index 0000000..ae2ed30 --- /dev/null +++ b/REST-API.md @@ -0,0 +1,442 @@ +# Справочник REST API: Система расписания университета + +Базовый URL: `/api` + +--- + +## 1. Аутентификация (`/api/auth`) + +### `POST /api/auth/login` — Вход в систему + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Описание | +|------------|--------|:------------:|-----------------------------------| +| `username` | String | ✅ | Логин пользователя | +| `password` | String | ✅ | Пароль пользователя | + +**Тело ответа (JSON) — `LoginResponse`:** + +| Поле | Тип | Присутствие | Описание | +|------------|---------|-------------------------|--------------------------------------------------------------| +| `success` | Boolean | Всегда | `true` при успешном входе, `false` при ошибке | +| `message` | String | Всегда | `"OK"` или сообщение об ошибке | +| `token` | String | Только при `success=true`| UUID-токен сессии | +| `role` | String | Только при `success=true`| Роль: `ADMIN`, `TEACHER` или `STUDENT` | +| `redirect` | String | Только при `success=true`| URL для редиректа: `/admin/`, `/teacher/` или `/student/` | + +**Коды ответа:** `200 OK`, `401 Unauthorized` + +--- + +## 2. Пользователи (`/api/users`) + +### `GET /api/users` — Список всех пользователей + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `UserResponse[]`:** + +| Поле | Тип | Описание | +|------------|--------|-------------------------------------------| +| `id` | Long | ID пользователя | +| `username` | String | Логин пользователя | +| `role` | String | Роль: `ADMIN`, `TEACHER` или `STUDENT` | + +--- + +### `GET /api/users/teachers` — Список преподавателей + +**Параметры запроса:** Нет + +**Тело ответа:** Массив `UserResponse[]` (формат аналогичен `/api/users`, но только пользователи с ролью `TEACHER`). + +--- + +### `POST /api/users` — Создание пользователя + +**Тело запроса (JSON) — `CreateUserRequest`:** + +| Поле | Тип | Обязательное | Валидация | Описание | +|------------|--------|:------------:|------------------------------------|-------------------------------------| +| `username` | String | ✅ | Не пустое, уникальное | Логин нового пользователя | +| `password` | String | ✅ | Минимум 4 символа | Пароль (хэшируется через BCrypt) | +| `role` | String | ✅ | Одно из: `ADMIN`, `TEACHER`, `STUDENT` | Роль пользователя | + +**Тело ответа:** `UserResponse` (при успехе) + +**Коды ответа:** `200 OK`, `400 Bad Request` (с полем `message`) + +--- + +### `DELETE /api/users/{id}` — Удаление пользователя + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|-------------------| +| `id` | Long | ✅ | ID пользователя | + +**Тело ответа:** `{ "message": "Пользователь удалён" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 3. Аудитории (`/api/classrooms`) + +### `GET /api/classrooms` — Список всех аудиторий + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `ClassroomResponse[]`:** + +| Поле | Тип | Описание | +|---------------|------------------|-----------------------------------| +| `id` | Long | ID аудитории | +| `name` | String | Название/номер аудитории | +| `capacity` | Integer | Вместимость | +| `isAvailable` | Boolean | Доступна ли аудитория | +| `equipments` | Equipment[] | Список оборудования (объекты с `id` и `name`) | + +--- + +### `POST /api/classrooms` — Создание аудитории + +**Тело запроса (JSON) — `ClassroomRequest`:** + +| Поле | Тип | Обязательное | По умолчанию | Валидация | Описание | +|----------------|----------|:------------:|:------------:|------------------------|---------------------------------| +| `name` | String | ✅ | — | Не пустое, уникальное | Название/номер аудитории | +| `capacity` | Integer | ✅ | — | Больше нуля | Вместимость | +| `isAvailable` | Boolean | ❌ | `true` | — | Доступна ли аудитория | +| `equipmentIds` | Long[] | ❌ | `[]` | ID существующего оборудования | Список ID привязанного оборудования | + +**Тело ответа:** `ClassroomResponse` + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `PUT /api/classrooms/{id}` — Обновление аудитории + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|----------------| +| `id` | Long | ✅ | ID аудитории | + +**Тело запроса (JSON) — `ClassroomRequest` (все поля опциональны при обновлении):** + +| Поле | Тип | Обязательное | Валидация | Описание | +|----------------|----------|:------------:|--------------------------------|---------------------------------| +| `name` | String | ❌ | Не пустое, уникальное (если передаётся) | Новое название | +| `capacity` | Integer | ❌ | Больше нуля (если передаётся) | Новая вместимость | +| `isAvailable` | Boolean | ❌ | — | Новый статус доступности | +| `equipmentIds` | Long[] | ❌ | — | Новый список ID оборудования (полная замена) | + +**Тело ответа:** `ClassroomResponse` + +**Коды ответа:** `200 OK`, `400 Bad Request`, `404 Not Found` + +--- + +### `DELETE /api/classrooms/{id}` — Удаление аудитории + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|----------------| +| `id` | Long | ✅ | ID аудитории | + +**Тело ответа:** `{ "message": "Аудитория удалена" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 4. Оборудование (`/api/equipments`) + +### `GET /api/equipments` — Список всего оборудования + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `Equipment[]`:** + +| Поле | Тип | Описание | +|--------|--------|--------------------------| +| `id` | Long | ID оборудования | +| `name` | String | Название оборудования | + +--- + +### `POST /api/equipments` — Создание оборудования + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Валидация | Описание | +|--------|--------|:------------:|-----------------------|-----------------------| +| `name` | String | ✅ | Не пустое, уникальное | Название оборудования | + +**Тело ответа:** `Equipment` (объект с `id` и `name`) + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `DELETE /api/equipments/{id}` — Удаление оборудования + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|-------------------| +| `id` | Long | ✅ | ID оборудования | + +**Тело ответа:** `{ "message": "Оборудование удалено" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 5. Дисциплины (`/api/subjects`) + +### `GET /api/subjects` — Список всех дисциплин + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `Subject[]`:** + +| Поле | Тип | Описание | +|--------|--------|----------------------| +| `id` | Long | ID дисциплины | +| `name` | String | Название дисциплины | + +--- + +### `POST /api/subjects` — Создание дисциплины + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Валидация | Описание | +|--------|--------|:------------:|-----------------------|----------------------| +| `name` | String | ✅ | Не пустое, уникальное | Название дисциплины | + +**Тело ответа:** `Subject` (объект с `id` и `name`) + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `DELETE /api/subjects/{id}` — Удаление дисциплины + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|------------------| +| `id` | Long | ✅ | ID дисциплины | + +**Тело ответа:** `{ "message": "Дисциплина удалена" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 6. Формы обучения (`/api/education-forms`) + +### `GET /api/education-forms` — Список форм обучения + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив объектов:** + +| Поле | Тип | Описание | +|--------|--------|-------------------------| +| `id` | Long | ID формы обучения | +| `name` | String | Название формы обучения | + +--- + +### `POST /api/education-forms` — Создание формы обучения + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Валидация | Описание | +|--------|--------|:------------:|-----------------------|-------------------------| +| `name` | String | ✅ | Не пустое, уникальное | Название формы обучения | + +**Тело ответа:** `{ "id": Long, "name": String }` + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `DELETE /api/education-forms/{id}` — Удаление формы обучения + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|---------------------| +| `id` | Long | ✅ | ID формы обучения | + +> [!IMPORTANT] +> Удаление невозможно, если к форме обучения привязаны группы. Сначала необходимо удалить или перепривязать группы. + +**Тело ответа:** `{ "message": "Форма обучения удалена" }` или ошибка `{ "message": "Невозможно удалить: есть привязанные группы (N)" }` + +**Коды ответа:** `200 OK`, `400 Bad Request`, `404 Not Found` + +--- + +## 7. Группы (`/api/groups`) + +### `GET /api/groups` — Список всех групп + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `GroupResponse[]`:** + +| Поле | Тип | Описание | +|---------------------|--------|---------------------------------| +| `id` | Long | ID группы | +| `name` | String | Название группы | +| `educationFormId` | Long | ID формы обучения | +| `educationFormName` | String | Название формы обучения | + +--- + +### `POST /api/groups` — Создание группы + +**Тело запроса (JSON) — `CreateGroupRequest`:** + +| Поле | Тип | Обязательное | Валидация | Описание | +|-------------------|--------|:------------:|-----------------------------------|-----------------------------------| +| `name` | String | ✅ | Не пустое, уникальное | Название группы | +| `educationFormId` | Long | ✅ | Должен существовать в БД | ID формы обучения | + +**Тело ответа:** `GroupResponse` + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `DELETE /api/groups/{id}` — Удаление группы + +**Параметры пути:** + +| Параметр | Тип | Обязательное | Описание | +|----------|------|:------------:|-------------| +| `id` | Long | ✅ | ID группы | + +**Тело ответа:** `{ "message": "Группа удалена" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 8. Привязка преподавателей к дисциплинам (`/api/teacher-subjects`) + +### `GET /api/teacher-subjects` — Список всех привязок + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `TeacherSubjectResponse[]`:** + +| Поле | Тип | Описание | +|---------------|--------|----------------------------| +| `userId` | Long | ID преподавателя | +| `username` | String | Логин преподавателя | +| `subjectId` | Long | ID дисциплины | +| `subjectName` | String | Название дисциплины | + +--- + +### `POST /api/teacher-subjects` — Создание привязки + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Валидация | Описание | +|-------------|------|:------------:|----------------------------------|----------------------| +| `userId` | Long | ✅ | Преподаватель должен существовать | ID преподавателя | +| `subjectId` | Long | ✅ | Дисциплина должна существовать, привязка уникальна | ID дисциплины | + +**Тело ответа:** `{ "message": "Привязка создана" }` + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `DELETE /api/teacher-subjects` — Удаление привязки + +**Тело запроса (JSON):** + +| Поле | Тип | Обязательное | Описание | +|-------------|------|:------------:|----------------------| +| `userId` | Long | ✅ | ID преподавателя | +| `subjectId` | Long | ✅ | ID дисциплины | + +**Тело ответа:** `{ "message": "Привязка удалена" }` + +**Коды ответа:** `200 OK`, `404 Not Found` + +--- + +## 9. Занятия / Расписание (`/api/users/test`) + +### `GET /api/users/test` — Список всех занятий + +**Параметры запроса:** Нет + +**Тело ответа (JSON) — массив `LessonResponse[]`:** + +| Поле | Тип | Описание | +|----------------|--------|-------------------------| +| `id` | Long | ID занятия | +| `teacherId` | Long | ID преподавателя | +| `groupId` | Long | ID группы (может быть `null` в ответе) | +| `lessonTypeId` | Long | ID типа занятия / предмета | +| `day` | String | День недели | +| `week` | String | Чётность недели | +| `time` | String | Время занятия | + +--- + +### `POST /api/users/test/create` — Создание занятия + +**Тело запроса (JSON) — `CreateLessonRequest`:** + +| Поле | Тип | Обязательное | Валидация | Описание | +|----------------|--------|:------------:|----------------|-------------------------------| +| `teacherId` | Long | ✅ | Не `null`, не `0` | ID преподавателя | +| `groupId` | Long | ✅ | Не `null`, не `0` | ID группы | +| `lessonTypeId` | Long | ✅ | Не `null`, не `0` | ID типа занятия / предмета | +| `day` | String | ✅ | Не пустое | День недели | +| `week` | String | ✅ | Не пустое | Чётность недели | +| `time` | String | ✅ | Не пустое | Время занятия | + +**Тело ответа:** `LessonResponse` (поля: `lessonTypeId`, `day`, `week`, `time`) + +**Коды ответа:** `200 OK`, `400 Bad Request` + +--- + +### `GET /api/users/test/ping` — Проверка доступности + +**Параметры запроса:** Нет + +**Тело ответа:** `"pong"` (plain text) + +**Коды ответа:** `200 OK` + +--- + +## Общий формат ошибок + +Все `400 Bad Request` ответы имеют формат: + +```json +{ + "message": "Текст ошибки на русском языке" +} +``` + +На `404 Not Found` — возвращается пустое тело. \ No newline at end of file