Что такое HTTP API

API (Application Programming Interface) - это интерфейс программного взаимодействия. В контексте веба это означает: клиентская программа отправляет запрос по HTTP на сервер, сервер запускает нужную логику и возвращает результат. Вместо HTML страницы чаще всего приходит JSON, который удобно обрабатывать в коде.

Логика запрос - ответ остается той же, что и в обычном HTTP. Отличие в цели: мы обращаемся не к визуальной странице для человека, а к ресурсу или операции для программы. В ответ чаще приходит не HTML c версткой сайта, а результат выполнения логики сервера - вычисления, обработка информации и файлов, создание/обновление сущностей, запуск бизнес-операции и возврат структурированных данных.

Типовые сценарии использования

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

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

Базовый URL, endpoint и ресурс

В API обычно есть базовый URL (например https://api.example.com) и пути к конкретным ресурсам - endpoints, например /users или /posts/1. Путь показывает, с каким типом данных вы работаете.

Часто URL проектируют по REST подходу: используют существительные для ресурсов и методы HTTP для действий над этими ресурсами. Такой стиль делает API предсказуемым, упрощает интеграцию и снижает количество ошибок в команде.

Что такое endpoint

Endpoint - это конкретная точка API, то есть адрес, по которому доступна операция над ресурсом. Проще: endpoint = метод + путь. Один и тот же путь с разными методами может означать разные действия.

Примеры endpoint: GET /posts - получить список постов, GET /posts/1 - получить один пост, POST /posts - создать пост, DELETE /posts/1 - удалить пост. Поэтому в документации всегда читают не только URL, но и разрешенные методы.

REST подход детально

REST (Representational State Transfer) предложил Рой Филдинг (Roy Fielding) в своей докторской диссертации в 2000 году. Это архитектурный стиль для распределенных систем, а не отдельный протокол. HTTP оказался удобной транспортной основой для REST API.

Ключевые идеи REST: клиент-серверное разделение, отсутствие серверной сессии между запросами (stateless), единообразный интерфейс, адресуемость ресурсов через URI, кэширование, многоуровневая архитектура. Именно из-за этих ограничений REST API легче масштабировать и поддерживать.

Сколько методов и когда появились

На практике в API чаще всего используют 5-7 методов, но стандарт HTTP определяет больше: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH (PATCH стандартизован позже - RFC 5789, 2010). Базовые методы сформировались в ранних версиях HTTP/1.0-1.1, затем стандарт развивался через серию RFC.

Сегодня семантика методов и статус-кодов описана в RFC 9110 (HTTP Semantics), а официальный реестр поддерживает IANA. В прикладной разработке важно использовать методы по назначению, чтобы API было читаемым и совместимым с инструментами и прокси.

Path, query и тело запроса

Параметры в API передают несколькими способами. Path параметр - часть пути (например /posts/1, где 1 - id записи). Query параметры передаются после ? в формате key=value, а несколько параметров разделяются символом &. Важно: query параметры технически можно использовать почти с любым HTTP методом, но чаще всего вы встретите их именно в GET запросах для фильтрации, сортировки, поиска и пагинации.

Примеры готовых URL с query параметрами: https://jsonplaceholder.typicode.com/posts?userId=1, https://api.example.com/users?page=2&limit=20, https://api.example.com/search?q=http+api&lang=ru.

Для других видов запросов, таких как POST, PUT, PATCH, данные также передают в теле запроса, обычно в JSON. Какой способ использовать - зависит от смысла данных и документации API.

Почему в API чаще всего JSON

JSON удобен для машинной обработки и понятен человеку. Он компактнее XML, легко читается и поддерживается в большинстве языков программирования. Поэтому в современных HTTP API именно JSON обычно является форматом по умолчанию.

Сервер и клиент договариваются о формате через заголовки: Content-Type и Accept. Для JSON обычно используют application/json.

Что такое CRUD и откуда это название

CRUD - это аббревиатура от Create, Read, Update, Delete (создать, прочитать, обновить, удалить). Термин пришел из мира баз данных и информационных систем как минимальный набор операций над сущностью.

В HTTP API CRUD удобно использовать как ментальную модель проектирования: Create - POST, Read - GET, Update - PUT/PATCH, Delete - DELETE. Такой подход делает интерфейс API понятным даже новым разработчикам: по методу запроса сразу читается ожидаемое действие.

GET, POST, PUT, PATCH, DELETE

Для чтения ресурса обычно используют GET, для создания - POST, для полного обновления - PUT, для частичного обновления - PATCH, для удаления - DELETE. Это распространенная практика и основа REST-подхода.

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

Статусы, которые вы увидите чаще всего

HTTP статус ответа - это числовой код, который сервер возвращает в первой строке ответа, чтобы кратко сообщить результат обработки запроса. Это быстрый сигнал для клиента: операция успешна, требует действий клиента или завершилась ошибкой.

Для API особенно важны коды: 200 (успех), 201 (ресурс создан), 204 (успех без тела), 400 (ошибка в запросе), 401 (не авторизован), 403 (нет прав), 404 (не найдено), 500 (ошибка сервера).

Код ответа всегда нужно интерпретировать вместе с телом и заголовками. Например, 200 не всегда означает корректные бизнес данные, а 400 часто включает полезное описание ошибки в JSON.

1xx, 2xx, 3xx, 4xx, 5xx

Статусы делятся на пять групп по первой цифре: 1xx - информационные (промежуточные служебные ответы, например про продолжение обмена, а не финальный результат операции), 2xx - успешные, 3xx - перенаправления, 4xx - ошибки клиента, 5xx - ошибки сервера. Именно поэтому по одной цифре можно быстро понять класс проблемы.

Если смотреть на диапазоны, в каждой группе доступно по 100 числовых позиций (100-199, 200-299, 300-399, 400-499, 500-599), всего 500 потенциальных кодов. Реально стандартизована только часть. Исторически механизм статусов формировался в развитии HTTP спецификаций (RFC 1945, 2616, 7231), а в актуальном виде семантика закреплена в RFC 9110. Официальный реестр поддерживает IANA (HTTP Status Code Registry), а изменения проходят через IETF HTTP Working Group и выходят нечасто, по мере необходимости.

Приложение, фреймворк или инфраструктура

Статус может выставлять не только код разработчика. Его часто задают фреймворки и серверная инфраструктура: веб-серверы (программы, принимающие HTTP запросы), API gateway (входная точка API с политиками доступа и лимитами), reverse proxy (промежуточный сервер, который перенаправляет запросы к бэкендам), балансировщики (распределяют трафик между несколькими серверами). Например, приложение может вернуть 200, а gateway - 429 при лимитах или 502/504 при проблеме upstream (внутреннего целевого сервиса, к которому прокси пересылает запрос).

Устройства транспортного и сетевого уровней (маршрутизаторы, коммутаторы) не "ставят HTTP коды" как часть HTTP ответа, но могут влиять на доступность: потеря пакетов, разрыв соединения, таймаут TLS. Для клиента это проявляется не как HTTP код, а как сетевые ошибки соединения.

Интересные коды: 417 (Expectation Failed) и шуточный 418 (I'm a teapot). Код 417 означает, что сервер не смог выполнить условие из заголовка Expect (например Expect: 100-continue), то есть клиент ожидал специальный сценарий обмена, а сервер его не поддержал или отклонил.

Код 418 появился как шутка в документе RFC 2324 (Hyper Text Coffee Pot Control Protocol, 1998) и стал культурной частью HTTP-сообщества. Позже при обновлении спецификаций обсуждали его исключение из основной линии документов, но сообщество разработчиков активно выступило за сохранение, поэтому 418 остался как узнаваемый исторический код-мем.

Назначение групп HTTP статусов

1. Какая группа означает успешную обработку запроса?

2. Какая группа обычно говорит, что проблема в запросе клиента?

3. Какая группа чаще указывает на сбой на стороне сервера?

4. Какая группа связана с перенаправлениями?

Минимальный набор для практики

В большинстве лабораторных достаточно двух заголовков: Accept: application/json и Content-Type: application/json (для запросов с телом). Если требуется доступ к защищенному API, добавляют Authorization: Bearer <token>.

Некоторые клиенты, например Postman, часть заголовков добавляют автоматически. В curl вы задаете их явно через параметр -H.

Почему сначала читаем спецификацию

Перед отправкой запросов всегда открывайте документацию: базовый URL, доступные методы, обязательные поля, форматы дат, правила авторизации, ограничения и примеры. Во многих API используется OpenAPI (Swagger), где это представлено структурировано.

Swagger (инструменты экосистемы OpenAPI) полезен тем, что дает интерактивную документацию: видно схему запросов/ответов, обязательные поля, статусы и можно отправлять тестовые запросы прямо из браузера. Это ускоряет обучение API и снижает число ошибок при интеграции. Пример: Swagger UI.

Хорошая документация экономит время: вы сразу понимаете, какие параметры можно передавать в query, какие - в body, и какой код ответа должен считаться успешным для конкретного метода.

Что такое Postman

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

В учебных и ранних этапах разработки Postman часто фактически заменяет фронтенд: вы можете проверить бизнес-логику API, контракты и статусы еще до появления пользовательского интерфейса. Это ускоряет разработку и облегчает командное тестирование.

Почему командная строка все еще важна

curl (Client URL) - универсальная консольная утилита для сетевых запросов, созданная Даниэлем Стенбергом в 1998 году. Она поддерживает множество протоколов и особенно полезна для HTTP API, когда нужен быстрый вызов из терминала или скрипта.

В большинстве современных ОС curl уже предустановлен или ставится одной командой. Преимущества: удобно для серверов и CI/CD без GUI (графического интерфейса), легко вставляется в shell-скрипты, прозрачно показывает запрос и ответ. По сравнению с Postman curl лучше для автоматизации, а по сравнению со строкой браузера позволяет гибко управлять методами, заголовками и телом. По сравнению с библиотеками в бэкенде это быстрый способ изолированно проверить API без написания кода приложения.

-X, -H, -d, -i, -v, -o

-X задает метод, -H добавляет заголовок, -d передает тело запроса, -i выводит заголовки ответа вместе с телом, -v показывает подробный обмен, -o сохраняет ответ в файл.

Если метод не задан, curl использует GET. Если вы добавили -d, curl обычно отправляет POST, но для учебных задач лучше всегда явно указывать метод через -X.

HTTPS, токены и аккуратность в логах

Для реальных систем используйте HTTPS, чтобы заголовки и тело запроса не передавались в открытом виде. Токены доступа нельзя публиковать в скриншотах и логах, особенно при использовании флага -v в curl.

Флаг -v (verbose) включает подробный режим: показывает детали сетевого обмена, отправленные и полученные заголовки, информацию о соединении и TLS. Это очень полезно для диагностики, но именно поэтому в выводе могут оказаться чувствительные данные.

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

Почему в API появляется /v1

API развивается: добавляются поля, меняется поведение, устаревают методы. Чтобы не ломать старых клиентов, вводят версии - например /api/v1, /api/v2. Клиент должен явно знать, к какой версии он обращается.

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

Как API возвращает большие списки

Списки ресурсов часто отдают частями: параметрами page, limit, offset. Это защищает сервер от перегрузки и ускоряет интерфейс клиента. Дополнительно используют фильтры и сортировку в query параметрах.

Если API возвращает 10 000 записей одной страницей, это плохой дизайн. Гораздо лучше сделать предсказуемую пагинацию и метаинформацию в ответе: общее число элементов, номер страницы, размер страницы. Для просмотра больших JSON удобно использовать JSON Viewer инструменты (например расширения браузера JSON Viewer, JSON Formatter, встроенный pretty view в Postman) - они позволяют сворачивать узлы и быстрее читать структуру ответа.

Типичные проблемы при вызове API

Частые ошибки: неверный URL, пропущенный заголовок Content-Type, невалидный JSON, отсутствие обязательного поля, неверный токен, не тот метод HTTP, ошибки кодировки. Проверяйте сначала код ответа, потом тело с описанием ошибки.

Иногда проблема не в запросе, а в окружении: прокси, DNS, ограничения сети, время жизни токена. Поэтому полезно сравнить один и тот же запрос в Postman и curl - так проще локализовать источник сбоя.

Как увидеть API на сетевом уровне

Если запросы идут по HTTP, в Wireshark можно увидеть метод, путь, заголовки и JSON тело в явном виде. Для HTTPS содержимое зашифровано, но остаются видны общие параметры соединения и метаданные сессии.

Это полезно для диагностики: если приложение "молчит", можно проверить, ушел ли вообще запрос и какой код ответа пришел с сервера.

Как правильно изучать новый API

Рабочий алгоритм: открыть документацию, выполнить простой GET, проверить структуру ответа, затем попробовать POST c минимальным корректным телом, после этого проверить PUT/PATCH и DELETE. На каждом шаге фиксировать коды и поля ответа.

Если запрос не проходит - уменьшите сложность: уберите лишние параметры и возвращайтесь к минимальному рабочему примеру. Это ускоряет поиск ошибки.

Когда API отвечает 500

Если API внезапно отдает 500, не паникуйте - это не ваш ноутбук "сломал интернет", а сервер честно сообщает, что ему сейчас плохо. Ваша задача - сохранить спокойствие, проверить входные данные и логично продолжить отладку.

Профессиональный подход в сетях - это не отсутствие ошибок, а системная проверка гипотез шаг за шагом.

Что вы должны уметь перед практикой

Перед началом лабораторной вы должны уверенно различать endpoint, параметры, заголовки, тело запроса, коды ответа и назначение методов GET, POST, PUT/PATCH, DELETE. Также важно понимать, как один и тот же вызов выполнить в Postman и в curl.

Дальше - интерактивные задания, затем финальный допуск. После успешного прохождения откроется практический блок на 20 шагов с действиями за компьютером.

CRUD и методы HTTP

Сопоставьте операцию с наиболее типичным HTTP методом.

Выберите корректный URL с параметрами

Какой вариант передает два query параметра lang=ru и fields=city?

Инструмент и действие

Сопоставьте действие с инструментом, где это чаще всего делают.

Что нужно для POST JSON

Выберите верные утверждения (можно несколько).

Краткий тест (8 вопросов)

Для доступа к практике нужно набрать не менее 80% (минимум 7 из 8 правильных ответов).

1. API в контексте веба обычно работает по модели:

2. Для чтения ресурса чаще всего используют:

3. Код 201 обычно означает:

4. Какой заголовок указывает формат тела JSON:

5. В curl заголовок добавляют ключом:

6. Какой формат данных чаще всего встречается в HTTP API:

7. Query параметры в URL начинаются после символа:

8. Для удаления ресурса по REST рекомендации обычно используют:

Практика: HTTP API в Postman и curl

В этой части выполните 20 шагов за компьютером: подготовка среды, GET, POST, PUT, DELETE, добавление query параметров и заголовков, сравнение результатов в Postman и curl, а затем самопроверка. Для лабораторной используем публичный сервис jsonplaceholder.typicode.com.

Откройте Postman и терминал

Создайте первый GET запрос в Postman

jsonplaceholder.typicode.com - это публичный учебный fake API для тестов и обучения, где можно безопасно тренировать GET/POST/PUT/PATCH/DELETE без доступа к реальной продакшен базе. Сайт: jsonplaceholder.typicode.com.

Убедитесь, что получили статус 200 и JSON с полями userId, id, title, body.

Проверьте тот же GET в curl

Сравните тело ответа с результатом в Postman - данные должны быть одинаковыми.

Посмотрите заголовки ответа в curl

Найдите строку статуса и заголовок Content-Type.

GET список ресурсов с query параметром

Проверьте, что вернулся массив постов пользователя с id 1.

Повторите query запрос в curl

Обратите внимание: URL с параметрами удобно брать в кавычки.

Создайте POST запрос в Postman

Отправьте запрос и проверьте статус 201.

Сделайте POST в curl

Пояснение по флагам: -X POST - метод запроса, -H - заголовок (здесь формат тела JSON), -d - тело запроса. Без Content-Type: application/json некоторые API не смогут корректно распарсить тело.

Сверьте код ответа и структуру JSON с Postman.

Проверьте PUT обновление в Postman

Отправьте и проверьте статус 200.

Выполните PUT через curl

Сравните ответ с Postman.

Попробуйте PATCH (частичное обновление)

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

Проверьте DELETE в Postman и curl

Зафиксируйте код ответа (обычно 200 или 204 в учебных API).

Добавьте заголовок Accept

Заголовок Accept сообщает серверу, какой формат ответа клиент предпочитает получить. Это не "формат тела запроса", а именно пожелание к формату ответа (например JSON, XML, text).

Убедитесь, что формат ответа соответствует ожиданию.

Сохраните ответ curl в файл

Откройте файл post1.json в редакторе и проверьте содержимое.

Посмотрите подробный обмен в curl

Найдите в выводе отправленные заголовки запроса и строку статуса ответа.

Соберите мини-коллекцию в Postman

Запускайте запросы из коллекции по очереди и контролируйте коды ответа.

Опционально: посмотрите трафик в Wireshark

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

Сравните Postman и curl

Запишите 2-3 вывода: в чем Postman удобнее для ручной работы и в чем curl удобнее для автоматизации.

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

Ответьте себе без отправки:

• Какие коды ответа вы получили для GET, POST, PUT/PATCH и DELETE?
• Какой заголовок обязателен, если отправляете JSON в теле запроса?
• Как в curl добавить заголовок и как передать тело?
• Какая разница между PUT и PATCH в вашем понимании?

Финал практики

Практика завершена. Вы выполнили основные операции HTTP API, научились отправлять запросы в Postman и в curl, читать коды ответа и работать с JSON. Следующая тема курса продолжит прикладной уровень и перейдет к DNS.

При желании повторите лабораторную на другом публичном API и добавьте авторизацию по токену - это хороший следующий шаг для закрепления.

Сохранение и просмотр заголовков

Работа с timeout

Пользовательский User-Agent

Это полезно в интеграциях и логировании, чтобы сервер видел источник вызова.

Итог по расширенной практике curl

Вы потренировали дополнительные возможности curl: вывод заголовков, сохранение ответа, ограничение времени и кастомные заголовки. Эти приемы особенно полезны в реальных задачах DevOps и бэкенд-диагностики.