Почему тема HTTP API так важна

Сегодня почти любое приложение общается с сервером через API. Даже если пользователь видит кнопку или форму, под капотом почти всегда отправляется HTTP-запрос.

• Веб, mobile, CRM, чат-боты - все опираются на API
• API связывает интерфейс, backend и внешние сервисы
• Понимание API упрощает диагностику сетевых проблем

Что такое HTTP API

HTTP API - это программный интерфейс, доступный по протоколу HTTP. Клиент обращается к адресу endpoint, передает параметры, а сервер возвращает структурированный ответ.

• API - правила общения программ
• HTTP - транспорт этих запросов и ответов
• Чаще всего ответ приходит в JSON

Рис.: клиент отправляет HTTP-запрос на URL endpoint, сервер возвращает ответ, часто в формате JSON

Endpoint: адрес конкретной операции

Когда говорят "вызвать API", обычно имеют в виду обращение к конкретному endpoint - сочетанию HTTP-метода и пути.

• GET /users - получить список
• GET /users/42 - получить один объект
• POST /users - создать новый объект

Один и тот же путь с разными методами может означать разные действия.

Из чего состоит HTTP-запрос

• Метод: GET, POST, PATCH и другие
• URL: домен, путь, query-параметры
• Headers: служебные метаданные
• Body: данные запроса, если они нужны

Из чего состоит HTTP-ответ

• Status code показывает общий результат
• Headers описывают формат, кэш, cookies, тип данных
• Body содержит полезный результат или описание ошибки

Диагностировать ответ нужно не только по коду, но и по содержимому тела.

Почему JSON стал стандартом по умолчанию

Большинство современных HTTP API использует JSON (JavaScript Object Notation), потому что он компактный, читаемый человеком и хорошо поддерживается в языках программирования.

• Объекты и массивы легко сериализуются
• Структура подходит для web и mobile
• Postman особенно удобен именно с JSON

Методы HTTP: быстрый обзор

• GET - чтение данных
• POST - создание или запуск операции
• PUT - полная замена ресурса
• PATCH - частичное изменение
• DELETE - удаление

В реальном API семантика может отличаться, но этот набор - базовый инженерный минимум.

GET: самый частый метод для чтения

Метод GET запрашивает данные и по соглашению не должен менять состояние на сервере.

• Параметры часто передаются в query string
• GET удобно кэшировать и повторять
• Типичный пример: фильтры, списки, поиск

POST: создание и запуск действий

POST используют, когда нужно передать данные на сервер и инициировать обработку.

• Создание заказа, регистрации, комментария
• Логин и выдача токена
• Запуск вычисления или фоновой задачи

PUT, PATCH и DELETE

• PUT - заменить ресурс целиком
• PATCH - изменить только часть полей
• DELETE - удалить ресурс или пометить как удаленный

На практике чаще всего студенты встречают PATCH, потому что API обновляют объект частично.

Полезные свойства методов: safe и idempotent

Safe и idempotent - это не сленг, а формальные термины из спецификаций HTTP. Ими описывают поведение метода: можно ли ожидать изменения данных и что произойдет при повторной отправке того же запроса.

• Safe - запрос предназначен только для чтения и не должен менять состояние сервера
• Idempotent - один и тот же запрос можно повторить много раз, итоговый результат останется тем же
• GET, HEAD, OPTIONS обычно safe; PUT и DELETE - не safe, но idempotent; POST чаще всего не idempotent

Эти свойства нужны не только для документации. На них опираются кэширование, повторные запросы при сетевых сбоях, работа прокси, браузеров, балансировщиков и клиентских библиотек. Например, если GET оборвался, его обычно можно безопасно повторить; а повторный POST может случайно создать объект дважды.

Коды статуса: язык обратной связи от сервера

• 1xx - служебные промежуточные ответы
• 2xx - операция выполнена успешно
• 3xx - перенаправление
• 4xx - ошибка на стороне клиента
• 5xx - проблема на стороне сервера

Почти любой анализ API начинается с чтения status code.

Какие статусы встречаются чаще всего

• 200 OK - успешное чтение или обновление
• 201 Created - объект создан
• 400 Bad Request - запрос некорректен
• 401 Unauthorized, 403 Forbidden - проблемы доступа
• 404 Not Found, 500 Internal Server Error

Headers: важная часть контракта API

• Content-Type - формат тела
• Authorization - токен или другой способ доступа
• Accept - какой ответ хочет клиент
• User-Agent и Cookie - контекст клиента

Студенты часто смотрят только на body, но очень много проблем скрывается именно в headers.

Как API обычно защищают доступ

• API key - простой идентификатор клиента
• Bearer token - частый способ авторизации; пример: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
• Cookies и сессии - типично для web-приложений
• OAuth 2.0 - протокол выдачи и делегирования доступа, а не способ кодирования строки, поэтому он не равен Base64

Документация API: без нее работать неудобно

Хорошее API почти всегда сопровождается документацией. Именно она задает ожидаемые параметры, форматы ответов, ошибки и правила аутентификации.

• Ищем base URL и список endpoint
• Проверяем обязательные headers и body
• Смотрим примеры ответов и ошибок

Swagger появился как набор инструментов для описания и тестирования REST API примерно в 2011 году. Позже его спецификация выросла в стандарт OpenAPI; с 2016 года развитие координирует инициатива OpenAPI Initiative. На практике OpenAPI - это формат описания API, а Swagger - популярные инструменты для визуализации, генерации и тестирования такой спецификации. Полезные ссылки: swagger.io и openapis.org.

Почему основной акцент делаем на Postman

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

• Не нужно помнить синтаксис команд сразу
• Видны query, headers, body, auth в отдельных вкладках
• Легче повторять и сравнивать запросы

Интерфейс Postman: что важно знать сразу

• Строка метода и URL - верхняя часть окна
• Вкладки Params, Authorization, Headers, Body
• Панель ответа с кодом, временем и телом
• Коллекции слева для сохранения запросов

Первый запрос в Postman

• Выбрать метод GET
• Вставить URL endpoint
• Нажать Send
• Посмотреть status, headers, body

Это базовый цикл, который студент должен довести до автоматизма.

Path params и query params в Postman

Две частые зоны ошибок - это параметры в пути и параметры в строке запроса.

• /users/42 - path parameter
• ?page=2&limit=10 - query parameters
• Postman умеет показывать и редактировать query отдельно

Если параметры переданы неверно, очень часто приходит 400 или пустой результат.

Вкладки Headers, Body и Authorization

• В Headers передаем тип контента и токены
• В Body отправляем JSON, form-data или raw-text
• Во вкладке Authorization Postman подставляет токен сам

Переменные и окружения в Postman

Когда проект растет, руками менять домены, токены и id неудобно. Для этого в Postman есть переменные.

• {{baseUrl}} - адрес сервера
• {{token}} - токен авторизации
• {{userId}} - id тестового объекта

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

Collections: как навести порядок в запросах

• Сохраняем запросы не вразнобой, а в коллекции
• Группируем по модулям: auth, users, orders
• Коллекция помогает повторять сценарии и делиться ими

Для курса это полезно еще и потому, что студент может возвращаться к уже проверенным запросам без ручного набора.

Тесты в Postman: простая автоматизация

Postman умеет не только отправлять запрос, но и проверять ответ скриптом.

• Проверка статуса 200
• Проверка наличия поля в JSON
• Сохранение токена из ответа в переменную

Как отлаживать ошибки в Postman

• Сначала читаем status code
• Потом смотрим body ошибки и headers
• Сравниваем URL, метод, auth и формат body
• При необходимости открываем Postman Console

Хорошая практика - менять только один параметр за раз, чтобы понять, что именно вызвало ошибку.

Импорт, экспорт и командная работа в Postman

• Можно импортировать коллекцию из JSON или по OpenAPI
• Можно экспортировать свои запросы преподавателю или команде
• Это удобно для лабораторных и повторяемых сценариев

Фактически коллекция Postman становится "живой документацией" по API.

Зачем тогда нужен curl

curl - это инструмент терминала для отправки HTTP-запросов. Он менее наглядный, но очень полезный для серверов, скриптов и быстрой проверки без GUI.

• Работает почти везде
• Хорошо подходит для автоматизации
• Удобен в документации и CI/CD

Базовые примеры curl

• -X задает метод
• -H добавляет заголовок
• -d передает тело

Полезные ключи curl в практике

• -i - показать headers ответа
• -v - подробный режим для диагностики
• -o file.json - сохранить ответ в файл
• -L - идти по редиректам
• --json - удобная передача JSON в новых версиях

Postman и curl: что выбирать студенту

• Для обучения и ручной проверки - прежде всего Postman
• Для серверной автоматизации и документации - curl
• Для уверенной инженерной практики нужно знать оба инструмента

Рабочий алгоритм студента при тестировании API

• Прочитать документацию и выписать endpoint
• Сначала отправить простой GET в Postman
• Потом проверить auth, headers и body
• Только после этого сравнить с curl или кодом

Такой порядок снижает хаос и помогает быстрее локализовать ошибку.

Полезные API для практики: простые стартовые сервисы

Полезные API: данные из реального мира

Полезные API: интересные сервисы для тренировки

Полезные сервисы для отладки, mock и проверки запросов

О чем надо помнить при работе с чужими API

• Могут быть лимиты запросов и rate limit
• Часть endpoint требует токен или API key
• Публичное API может менять контракт со временем
• Нельзя публиковать секреты и реальные токены

Поэтому всегда читаем документацию и аккуратно работаем с переменными окружения в Postman.

Итог лекции

• HTTP API - это контракт взаимодействия клиента и сервера
• Структуру запроса и ответа нужно читать целиком
• Основной учебный инструмент - Postman
• curl нужен для терминала, автоматизации и воспроизводимости
• Тренироваться лучше на безопасных публичных API

Если студент уверенно читает endpoint, метод, headers, body и status code, значит базовое понимание HTTP API уже сформировано.