Проектирование backend API

Курс помогает проектировать API, которые удобно использовать, тестировать и поддерживать после релиза. Студенты учатся думать не только о коде endpoint-а, но и о контракте, ошибках, документации и эксплуатации.

Для кого курс

• Backend-разработчики начального и среднего уровня.
• Frontend-разработчики, которым нужно лучше понимать API-контракты.
• QA-инженеры, пишущие API-тесты.
• Технические лиды учебных проектов.

Требования

• Понимание HTTP на базовом уровне.
• Опыт написания простых веб-приложений.
• Умение читать JSON.
• Желательно знать основы авторизации.

Неделя 1. Контракт и структура endpoint-ов

Темы

• Ресурсы и действия.
• Методы HTTP и их семантика.
• Именование endpoint-ов.
• Query-параметры, path-параметры и body.
• Единый формат ответа.
• Пагинация, сортировка и фильтрация.
• OpenAPI как договор между командами.

Практика

• Спроектировать API каталога курсов.
• Разобрать плохие имена endpoint-ов.
• Добавить пагинацию к списку объектов.
• Описать примеры запросов и ответов.

Домашнее задание

Подготовить черновой API-контракт для сервиса учебных программ: список курсов, карточка курса, создание черновика и публикация.

Неделя 2. Валидация, авторизация и ошибки

Темы

• Проверка входных данных на границе приложения.
• Разница между 400, 401, 403, 404, 409 и 500.
• Структура error response.
• Роли и минимальные права.
• Токены и срок действия.
• Rate limiting.
• Логирование ошибок без утечки секретов.

Практика

• Описать ошибки для endpoint-а создания курса.
• Разделить права автора, редактора и администратора.
• Добавить примеры невалидных запросов.
• Составить таблицу кодов ответа.

Домашнее задание

Сделать спецификацию ошибок для учебного API: формат, коды, сообщения для пользователя и диагностические поля для разработчика.

Неделя 3. Версионирование и эксплуатация

Темы

• Совместимые и несовместимые изменения.
• Версионирование через URL и заголовки.
• Deprecation policy.
• Health checks и readiness.
• Метрики и трассировка.
• Документация для потребителей API.
• Postman/HTTP-файлы для ручной проверки.

Практика

• Найти breaking changes в наборе правок.
• Подготовить health endpoint.
• Написать краткий changelog API.
• Составить smoke-test сценарий.

Домашнее задание

Провести ревью учебного API перед запуском: найти проблемы контракта, ошибок, безопасности и документации.

Финальный проект

Студенты проектируют API для платформы курсов:

• Каталог и карточка курса.
• Черновики программ.
• Публикация и откат версии.
• Роли редактора и администратора.
• Формат ошибок и примеры запросов.
• Минимальный набор smoke-тестов.

Контрольные вопросы

• Почему endpoint должен быть предсказуемым?
• Когда возвращать 403, а когда 404?
• Чем опасны подробные 500-ошибки?
• Как понять, что изменение API ломающее?
• Зачем документации нужны реальные примеры?

Лабораторные работы

Лабораторная 1. Контракт каталога

Студент проектирует API каталога курсов: список, карточка, фильтрация, сортировка и пагинация. Нужно описать примеры запросов и ответов.

Проверяется:

• предсказуемые URL;
• правильные HTTP-методы;
• единый формат ответа;
• понятная пагинация;
• отсутствие лишних полей.

Лабораторная 2. Ошибки и роли

Нужно описать поведение API для разных ролей: гость, студент, редактор и администратор. Для каждого сценария указываются статусы и body ошибки.

Проверяется:

• различие 401 и 403;
• отсутствие утечки внутренних деталей;
• единый формат ошибок;
• понятные сообщения;
• связь прав с бизнес-сценариями.

Лабораторная 3. Ревью версии API

Студент получает список изменений и должен определить, какие из них ломают совместимость, а какие можно выпускать без новой версии.

Проверяется:

• понимание backward compatibility;
• аккуратный changelog;
• deprecation-план;
• smoke-test сценарий;
• коммуникация с потребителями API.

Критерии оценки

• API можно понять по документации без устных пояснений.
• Ошибки помогают исправить запрос.
• Контракт не раскрывает внутреннюю реализацию.
• Версионирование имеет понятные правила.
• Примеры запросов соответствуют описанной схеме.

Типичные ошибки

• Использовать глаголы везде вместо ресурсов.
• Возвращать 200 для любой ошибки.
• Менять формат ответа без версии.
• Добавлять поля “на всякий случай”.
• Писать документацию без примеров.

Дополнительные темы

• OpenAPI и генерация клиентов.
• Contract testing.
• Idempotency keys.
• Rate limit headers.
• Correlation ID для трассировки запросов.

Результат

Студент сможет описать API-контракт, продумать ошибки, подготовить минимальную документацию для frontend-команды и сделать API более удобным для эксплуатации.