First API implementation

README.md

@@ -64,33 +64,45 @@ python main.py
 > `nginx`. Это также позволит вам использовать защищённое соединение, что
 > исключит возможность применения атаки Man-in-the-Middle для перехвата токена.
 
-Все запросы к веб-серверу требуют авторизации, используя HTTP заголовок
-`Authorization` и схему `Bearer`. Токен авторизации генерируется посредством
-взаимодействия с ботом в Matrix.
+Все запросы к веб-серверу являются GET-запросами и требуют авторизации.
+Авторизоваться можно двумя путями:
+1. Использовать HTTP-заголовок `Authorization` и схему `Bearer`. Например:
+   ```plain
+   Authorization: Bearer 1234567890abcdef
+   ```
+2. Использовать URL параметр `token`. Например:
+   ```plain
+   https://csonac.su/notify?token=f1829e94d...
+   ```
+Рекомендуется использовать первый способ (HTTP-заголовок), так как это позволяет
+избежать раскрытия токена в логах сервера и других местах, где можно посмотреть
+URL прошлых запросов.
 
 > Для каждого сервиса, использующего бота, рекомендуется генерировать свой
 > собственный токен. Это позволит отозвать токен только для одного серсива, если
 > токен будет украден.
 
 Доступные эндпоинты:
-- `POST /<channel>/notify`
-    - **Описание.** Используется, чтобы отправить уведомление в указанный канал.
-      Вместо `<channel>` указывается код канала, получаемый при помощи команды
-      `!info`, выполненной в комнате Matrix.
-    - **Тело запроса.** Тело запроса представляет собой `json` объект:
-      ```json
+- `GET /notify`
+    - **Описание.** Используется, чтобы отправить уведомление в канал.
+    - **Параметры запроса**
+      - `channel` - код канала, получаемый при помощи команды `!info`,
+        выполненной в комнате Matrix
+      - `service` - имя сервиса (учитывается, только если для токена не было
+        настроено имя сервиса через бота)
+      - `text` - текст уведомления (форматирование не поддерживается)
+    - **Ответ**
+      - В случае успеха сервер вернёт `200` и JSON следующего формата:
+        ```json
         {
-            "service": "<название сервиса; указывается, если токен это позволяет>",
-            "text": "<текст уведомления>"
+          "notification_id": "Notification ID will be here"
         }
-      ```
-    - **Тело ответа.** Тело ответа представляет собой `json` объект. В случае
-      успеха в нём будут все поля, перечисляемые ниже. В случае провала - только
-      поле `error`, содержащее текстовое описание ошибки.
-      ```json
+        ```
+        > В текущей версии `notification_id` не имеет практической пользы и его
+        > формат будет меняться.
+      - В случае ошибки сервер вернёт JSON следующего формата:
+        ```json
         {
-            "error": null,
-            "notification_id": "<здесь будет Notification ID>"
+          "detail": "Error description in English"
         }
-      ```
-- ``
+        ```