Юрий Белк – Full stack Developer (страница 33)

– 409 (если имя метки уникально в workspace)

GET /api/v1/workspaces/{workspaceId}/labels

Список меток.

Responses:

– 200 (можно без пагинации, но лучше с limit/cursor)

8.6.7. Webhooks / Notifications (минимальный контракт)

Если делаем webhooks:

– POST /api/v1/workspaces/{workspaceId}/webhooks – создать подписку

– GET /api/v1/workspaces/{workspaceId}/webhooks – список

– DELETE /api/v1/webhooks/{webhookId} – удалить

Модель webhook:

– url

– events (например task.created, comment.created)

– secret (для подписи)

– is_active

Для email-уведомлений в учебной версии часто достаточно “внутренней отправки” без внешнего API. Но события всё равно должны быть в аудит/логах.

8.7. Коды ответов и “мелкая гигиена API”

Несколько правил, которые повышают доверие к API:

– POST создание → 201 Created (+ тело созданного ресурса)

– DELETE успешный → 204 No Content

– PATCH успешный → 200 OK (+ обновлённый ресурс)

– GET список → 200 OK + { items, page }

И ещё:

– даты/время – в ISO 8601 (2026-01-01T12:34:56Z)

– идентификаторы – строки (часто удобнее и переносимее)

– не возвращайте поля, которые клиент не должен видеть (пароли, секреты)

8.8. Что можно установить, чтобы удобно работать с OpenAPI

– Swagger UI или любая UI-обёртка для просмотра спецификации

– Postman/Insomnia – импортировать спецификацию и тестировать запросы

– Редактор YAML/JSON с подсветкой схем (любой нормальный IDE/редактор справится)

8.9. Мини-итог главы

Мы превратили требования продукта в набор понятных договорённостей:

– endpoints,

– модель ошибок,

– модель пагинации,

– модель аутентификации,

– версия API.

Теперь можно переходить к реализации на любом языке, не споря “как лучше назвать поле” на каждом шаге – всё уже зафиксировано контрактом.

Раздел III. База данных (одна на всех)

Глава 9. PostgreSQL: схема данных

Эта глава – про то, как спроектировать схему в PostgreSQL так, чтобы:

– API работало быстро и предсказуемо,

– данные не превращались в кашу через месяц,

– изменения можно было вносить без паники.

Мы будем держаться принципа: половина теории, половина практики. То есть: сначала понятные правила, затем – как это выглядит в схеме и что с этим делать руками.

9.1. Почему именно PostgreSQL (и что от него ожидать)

PostgreSQL – это “швейцарский нож” для бэкенда:

– умеет транзакции и строгую целостность;

– богатый SQL (CTE, оконные функции, JSON, полнотекст);

– отличные индексы и оптимизатор;

– работает одинаково хорошо и на ноутбуке, и на сервере.

Если вы планируете разрабатывать и учиться – Postgres благодарный. Он не делает вид, что всё в порядке, когда данные уже сломаны. Он честный: либо можно, либо нельзя.

Что установить для работы (по желанию):

– PostgreSQL (локально или в Docker)

– любой GUI-клиент: DBeaver, DataGrip, pgAdmin (что удобнее)

– psql (терминальный клиент; полезен как минимум для “быстро проверить”)

– Docker + docker-compose (чтобы одинаково запускать окружение)

9.2. Модель данных TaskFlow: от домена к таблицам

Напомним домен:

– User

– Workspace + участники (membership)

– Project

– Task

– Comment

– Label + связь task-label (many-to-many)