cloud-file-storage: UI description replaced with REST API schema

zhukovsd · zhukovsd · commit d906a560dba4 · 2025-02-23T15:59:31.000+04:00
diff --git a/content/projects/cloud-file-storage.md b/content/projects/cloud-file-storage.md
@@ -13,8 +13,8 @@ weight = 6
 - [Maven/Gradle](../technologies/build-systems.md)
 - [Backend](../technologies/backend.md)
   - Spring Boot, Spring Security, Spring Sessions
-  - Thymeleaf
-  - Upload файлов, заголовки HTTP запросов, cookies, cессии
+  - REST, Swagger, Upload файлов
+  - Cookies, cессии
 - [Базы данных](../technologies/databases.md)
   - SQL
   - Spring Data JPA
@@ -31,6 +31,7 @@ weight = 6
 - Практика с Docker и Docker Compose
 - Первый проект, где студент самостоятельно разрабатывает структуру БД
 - Знакомство с NoSQL хранилищами - S3 для файлов, Redis для сессий
+- Интеграция по REST с одностраничным frontend приложением на React
 
 ## Функционал приложения
 
@@ -45,39 +46,294 @@ weight = 6
 - Загрузка (upload) файлов и папок
 - Создание новой пустой папки (аналогично созданию новой папки в проводнике)
 - Удаление
-- Переименование
+- Переименование и перемещение
 - Скачивание файлов и папок
 
-## Интерфейс приложения
+## REST API
 
-### Главная страница
+- Архитектурный стиль - RPC для авторизации и регистрации, REST для всего остального
+- Механизм авторизации - сессии
+- Формат запросов и ответов - JSON, кроме скачивания и аплоада файлов
 
-Адрес - `/?path=$path_to_subdirectory`. Параметр `$path` задаёт путь просматриваемой папки. Если параметр отсутствует, подразумевается корневая папка. Пример - `/path=Projects%2FJava%2FCloudFileStorage` (параметр закодирован через URL Encode).
+### Ответ в случае ошибки
 
-- Заголовок
-    - Для неавторизованных пользователей - кнопки регистрации и авторизации
-    - Для авторизованных пользователей - логин текущего пользователя и кнопка Logout
-- Контент (только для авторизованных пользователей)
-    - Форма поиска файлов и папок по названию
-    - Навигационная цепочка (breadcrumbs), содержащая путь из папок до текущей папки. Каждый элемент является ссылкой на свою папку. Пример - цепочка из папок, ведущая к - `Projects/Java/CloudFileStorage` содержала бы 3 папки - корневую, `Projects` и `Projects/Java`
-    - Список файлов в текущей директории. Для каждого файла отображаем имя и кнопку, вызывающее меню действий (удаление, переименование)
-    - Формы (или drop areas) для загрузки файлов и папок
+Актуально для всех методов.
 
-### Страница поиска файлов
+Тело ответа:
+```
+{
+  "message": "Текст ошибки"
+}
+```
 
-Адрес - `/search/?query=$search_query`.
+Тело ответа может содержать другие поля (которые по-умолчанию отправляет Spring).
 
-Неавторизованные пользователя не имеют доступа к данной странице, приложение должно редиректить их на форму авторизации.
+### Регистрация и авторизация
 
-- Заголовок
-    - Логин текущего пользователя и кнопка Logout
-- Контент
-    - Форма поиска файлов и папок по названию
-    - Список найденных файлов. Для каждого найденного файла отображаем имя и кнопку для перехода в папку, содержащую данный файл
+#### Регистрация
 
-### Остальное
+`POST /auth/sign-up`
 
-- Страницы с формами регистрации и авторизации
+Тело запроса (`application/json`):
+```
+{
+  "username": "user_1",
+  "password": "password"
+}
+```
+
+Ответ в случае успеха: `201 Created` со следующим телом:
+
+```
+{
+  "username": "user_1"
+}
+```
+
+При регистрации юзеру сразу создаётся сессия и выставляется кука.
+
+Коды ошибок:
+- 400 - ошибки валидации (пример - слишком короткий username)
+- 409 - username занят
+- 500 - неизвестная ошибка
+
+#### Авторизация
+
+`POST /auth/sign-in`
+
+Тело запроса (`application/json`):
+```
+{
+  "username": "user_1",
+  "password": "password"
+}
+```
+
+Тело ответа в случае успеха (`200 OK`):
+```
+{
+  "username": "user_1"
+}
+```
+
+Коды ошибок:
+- 400 - ошибки валидации (пример - слишком короткий username)
+- 401 - неверные данные (такого пользователя нет, или пароль неправильный)
+- 500 - неизвестная ошибка
+
+#### Выход из аккаунта (логаут)
+
+`POST /auth/sign-out`
+
+Тела запроса нет.
+
+Тело ответа в случае успеха (`204 No Content`) пустое.
+
+Коды ошибок:
+- 401 - запрос исполняется неавторизованным юзером
+- 500 - неизвестная ошибка
+
+### Пользователи
+
+#### Текущий пользователь
+
+`GET /user/me`
+
+Ответ в случае успеха: `200 OK` со следующим телом:
+
+```
+{
+  "username": "user_1"
+}
+```
+
+Коды ошибок:
+- 401 - пользователь не авторизован
+- 500 - неизвестная ошибка
+
+### Работа с файлами и папками
+
+Терминология:
+- Ресурс - файл или папка
+- Путь к ресурсу - полный путь состоит из иерархии папок, плюс имени ресурса
+  - Пример для файла - `folder1/folder2/file.txt`
+  - Пример для папки - `folder1/folder2`
+ 
+#### Ресурсы
+
+**Получение информации о ресурсе**
+
+`GET /resource?path=$path`
+
+Для всех запросов ниже, параметр path - полный путь к ресурсу в url-encoded формате. Путь к папке должен заканчиваться на `/`. Это необходимо, чтобы отличить папку и файл с одинаковым названием, которые могут сосуществовать вместе в одной корневой директории.
+
+Ответ в случае успеха: `200 OK` со следующим телом (`appication/json`):
+
+```
+{
+  "path": "folder1/folder2", // путь к папке, в которой лежит ресурс
+  "name": "file.txt",
+  "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+  "type": "DIRECTORY" // DIRECTORY или FILE
+}
+```
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь
+- 401 - пользователь не авторизован
+- 404 - ресурс не найден
+- 500 - неизвестная ошибка
+
+**Удаление ресурса**
+
+`DELETE /resource?path=$path`
+
+Ответ в случае успеха: `204 No Content` без тела:
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь
+- 401 - пользователь не авторизован
+- 404 - ресурс не найден
+- 500 - неизвестная ошибка
+
+**Скачивание ресурса**
+
+`GET /resource/download?path=$path`
+
+Ответ в случае успеха - `200 OK` и бинарное содержимое файла с Content-Type: `application/octet-stream`.
+
+Папка скачивается в формате zip архива её содержимого.
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь
+- 401 - пользователь не авторизован
+- 404 - ресурс не найден
+- 500 - неизвестная ошибка
+
+**Переименование/перемещение ресурса**
+
+`GET /resource/move?from=$from&to=$to`
+
+GET параметры - старый и новый полные пути к ресурсу в URL-encoded формате.
+
+- При переименовании меняется только имя файла
+- При перемещении меняется только путь к файлу
+
+Ответ в случае успеха - `200 OK`. Тело (`application/json`):
+```
+{
+  "path": "folder1/folder2", // путь к папке, в которой лежит перемещённый ресурс
+  "name": "file.txt", // имя перемещённого ресурса
+  "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+  "type": "DIRECTORY" // DIRECTORY или FILE
+}
+```
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь
+- 401 - пользователь не авторизован
+- 404 - ресурс не найден
+- 409 - ресурс, лежащий по пути `to` уже существует 
+- 500 - неизвестная ошибка
+
+**Поиск**
+
+`GET /resource/search?query=$query`
+
+GET параметр `query` - поисковый запрос в URL-encoded формате. 
+
+Ответ в случае успеха: `200 OK` со следующим телом (`appication/json`). Коллекция найденных ресурсов:
+
+```
+[
+  {
+    "path": "folder1/folder2", // путь к папке, в которой лежит ресурс
+    "name": "file.txt",
+    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+    "type": "DIRECTORY" // DIRECTORY или FILE
+  }
+]
+```
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий поисковый запрос
+- 401 - пользователь не авторизован
+- 500 - неизвестная ошибка
+
+**Аплоад**
+
+POST `resource?path=$path`
+
+GET параметр `path` - путь к папке, в которую мы загружаем ресурс(ы). 
+
+Тело запроса содержит данные из file input в формате MultipeartFile. Если в имени файла будет указана поддиректория (например, upload_folder/test.txt) - то при загрузке в storage_folder/ будет создана такая директория. В итоге файл после загрузки будет находиться в storage_folder/upload_folder/test.txt. Это позволяет загружать одним запросом файлы, целые папки и рекусривно вложенные подпапки одним запросом.
+
+Ответ в случае успеха: `201 Created` со следующим телом (`appication/json`). Коллекция загруженных ресурсов:
+
+```
+[
+  {
+    "path": "folder1/folder2", // путь к папке, в которой лежит ресурс
+    "name": "file.txt",
+    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+    "type": "DIRECTORY" // DIRECTORY или FILE
+  }
+]
+```
+
+Коды ошибок:
+- 400 - невалидное тело запроса
+- 404 - папка, в которую мы загружаем ресурс(ы) не существует
+- 401 - пользователь не авторизован
+- 500 - неизвестная ошибка
+
+**Папки**
+
+Получение информации о содержимом содержимом папки
+
+`GET /directory?path=$path`
+
+Ответ в случае успеха: `200 OK` со следующим телом (`appication/json`). Коллекция ресурсов, лежащих в папке (не ресурсивно):
+
+```
+[
+  {
+    "path": "folder1/folder2", // путь к папке, в которой лежит ресурс
+    "name": "file.txt",
+    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+    "type": "DIRECTORY" // DIRECTORY или FILE
+  }
+]
+```
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь
+- 401 - пользователь не авторизован
+- 404 - папка не существует
+- 500 - неизвестная ошибка
+
+**Создание пустой папки**
+
+`POST /directory?path=$path`
+
+Ответ в случае успеха: `201 Created` со следующим телом (`appication/json`). Ресурс созданной папки:
+
+```
+[
+  {
+    "path": "folder1/folder2", // путь к папке, в которой лежит ресурс
+    "name": "folder3",
+    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
+    "type": "DIRECTORY" // DIRECTORY или FILE
+  }
+]
+```
+
+Коды ошибок:
+- 400 - невалидный или отсутствующий путь к новой папке
+- 401 - пользователь не авторизован
+- 404 - Родительская папка не существует
+- 500 - неизвестная ошибка
 
 ## Работа с сессиями, авторизацией, регистрацией
 
