Учебный стенд
Service Desk API

§1Что это за сервис

Service Desk API — учебный сервис регистрации обращений в службу поддержки. Сотрудник сообщает о проблеме: «не работает VPN», «принтер в 312 печатает пустые листы». Каждое сообщение становится обращением с заголовком, описанием, статусом и временем создания. Специалист поддержки меняет статус: open → in_progress → closed.

Область выбрана так, чтобы в ней было всё, ради чего существуют правила API, и ничего лишнего. Здесь есть коллекция и отдельный объект, фильтрация и постраничный вывод, создание, частичное изменение, удаление, ошибки «не найдено», «нет прав» и «данные не по схеме». При этом нет сложной бизнес-логики, которая отвлекала бы от контракта.

Данные живут в памяти процесса: после перезапуска остаются три демонстрационных обращения. База данных здесь не нужна: контракт API от способа хранения не зависит.

§2Запуск за четыре шага

1. Получите проектСкачайте архив по ссылке выше (Code → Download ZIP) или выполните git clone https://github.com/MaximBytecamp/api-standard-template.git. Откройте папку в терминале.
2. Создайте окружениеВиртуальное окружение изолирует библиотеки проекта от системного Python.
3. Установите зависимостиВерсии закреплены в requirements.txt: у всех участников курса будет одинаковое поведение.
4. Запустите серверФлаг --reload перезапускает сервис при сохранении файла — это пригодится, когда вы начнёте менять код.

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process using WatchFiles
INFO:     Application startup complete.

Откройте в браузере http://127.0.0.1:8000/docs. Должна появиться страница Swagger UI: название сервиса, его версия и список операций, сгруппированных тегом Tickets.

§3Что внутри репозитория

Кода в проекте меньше, чем правил и проверок. Репозиторий устроен так намеренно: в этой дисциплине разбирается не реализация сервиса, а правила, по которым он описан и проверяется.

К каждой из этих папок мы вернёмся: openapi/ — в модуле 3, docs/ — в модуле 6, .github/ — в модуле 7.

§4Пять операций и два токена

Чтение открыто всем. Операции записи требуют токен — так в учебном сервисе показана разница между «сервер не знает, кто вы» и «сервер знает и не разрешает».

В Swagger UI токен вводится один раз: кнопка Authorize в шапке, поле Value, затем Authorize и Close. После этого интерфейс сам добавляет заголовок Authorization к запросам, у которых в контракте объявлена схема безопасности — у них в списке стоит значок замка.

§5Первый запрос

Прочитаем список обращений. Чтение токена не требует, поэтому команда короткая:

curl -i "http://127.0.0.1:8000/api/v1/tickets?limit=2"

HTTP/1.1 200 OK
content-type: application/json
x-request-id: 0b6f3c1e-2a9d-4a4f-9d7e-3f4a1c2b5d6e

{"items": [ … ], "total": 3, "limit": 2, "offset": 0}

Теперь создадим обращение. Здесь уже нужен токен, а вместе с ним — заголовок формата и тело:

curl -i -X POST http://127.0.0.1:8000/api/v1/tickets \
  -H "Authorization: Bearer demo-token" \
  -H "Content-Type: application/json" \
  -d '{"title": "Не работает VPN", "description": "После обновления клиента"}'

В ответе придёт код 201, заголовок location с адресом нового обращения и его тело. Попробуйте повторить ту же команду без строки с Authorization — сервер ответит 401 и телом в формате Problem Details. С токеном viewer-token ответ будет 403: клиент известен, но записывать ему нельзя.

Три ответа — 201, 401, 403 — на один и тот же запрос с разными токенами. Это и есть контракт в действии: поведение предсказуемо и описано заранее.

§6Что проект проверяет о себе сам

В репозитории лежат три проверки. Запустите их сразу после установки: так вы убедитесь, что окружение собрано правильно, и заодно увидите, что именно проверяется.

pytest
python scripts/export_openapi.py --check
npx @stoplight/spectral-cli lint openapi/openapi.yaml

...............................                                          [100%]
31 passed in 0.08s

# файлы описания совпадают с кодом — команда завершилась без сообщений

No results with a severity of 'warn' or higher found!

Те же три шага выполняет GitHub Actions при каждом изменении — об этом модуль 6. Запуск их локально до push экономит время: ошибку видно сразу, а не через две минуты в интерфейсе GitHub.

§7Если что-то не работает

Ниже — проблемы, которые встречаются чаще всего, и признак, по которому каждую из них узнают.