Методы API: язык команд и смыслов

19 августа, 2025 Просмотров 126 2 комментария

Сегодня вторник, а значит, с вами снова Юлия Чугунова, бизнес-аналитик, который любит аналитику не как модную профессию, а как способ жить и понимать мир вокруг. Задать точный вопрос, увидеть слабое место в процессе, найти закономерность в хаосе. Юлия пишет настоящий путеводитель, удобную, простую карту, по которой сможет пройти любой: начинающий аналитик, тестировщик, проджект или просто любознательный человек, которому нужно понять, как устроены системы. В прошлых статьях этой серии уже много и подробно написано про диаграммы, вопросы к заказчику, UX, базы данных… настало время API.

Наш герой уже видит архитектуру системы. Перед ним целая карта города: улицы, кварталы... Он может уверенно ткнуть лапой в любую точку и сказать: «Ага, вот здесь у нас склады данных, а тут живет модуль отчетности».

Но пока этот город пуст. Ни машин, ни пешеходов, ни даже кошки, перебегающей дорогу. Иногда, правда, он улавливает что-то странное: словно по невидимым дорогам проносятся быстрые гонцы, оставляя за собой только эхо слов. Система живет, просто герой еще не понимает ее языка.

Чтобы оживить этот город, нужно освоить искусство команд и смыслов-научиться говорить так, чтобы система отвечала, и слушать так, чтобы понимать ее. Это первый шаг к тому, чтобы архитектура перестала быть просто чертежом и стала живым диалогом.

Что такое API?

В большинстве современных систем-от небольших приложений до сложных распределенных платформ-рано или поздно возникает необходимость, чтобы ее части (модули, сервисы, компоненты) обменивались данными. Чтобы такой обмен был предсказуемым и понятным для всех участников, нужен общий язык.

Здесь на помощь приходит API (Application Programming Interface)¹-контракт и интерфейс взаимодействия между частями системы.

Мы в блоге уже писали не раз о том, что такое API и почему он очень важен. А также, как его тестировать и зачем. Все статьи вы можете найти, введя в строке поиска блога "api". Вот одна из них. А чтобы не пропускать интересное, подписывайтесь на наш блог, нажав кнопку ниже.

Итак, API задает правила:

что можно сделать (операции);
как это попросить (способ вызова);
в каком виде передать данные;
что получить в ответ;
какие коды/ошибки вернутся и в каком формате.

А на практике это означает, что один компонент или сервис может обратиться к другому с конкретной просьбой:

передать данные;
создать новый объект;
изменить существующий;
удалить ненужное.

API фактически как четкий протокол переговоров между двумя сторонами: ты знаешь, какие слова использовать, в каком порядке, и какой ответ услышишь. И чтобы этот язык ожил, у него есть свои «глаголы» – HTTP-методы. В этой статье говорим про HTTP-API; в других подходах (gRPC, GraphQL) семантика запросов другая.

Методы HTTP – «глаголы» API

В мире API методы HTTP, как мы уже сказали, словно глаголы в человеческом языке. Они не просто задают направление, а определяют саму суть действия. Выбор «глагола» решает, что система сделает с ресурсом: прочитает его, создаст, изменит или удалит.

Хотя в стандарте HTTP методов больше, в 90% рабочих задач используются пять основных.

GET – получить данные

«Покажи, что у тебя есть». Запрос на чтение, состояние не меняет (безопасный). Обычно без тела.

Пример: GET /jams – вернуть список всех джемов.

POST – создать

«Сделай новое». Создает новый объект. Обычно ID назначает сервер. Часто ответ-201 Created + Location.

Пример: POST /orders – оформить новый заказ.

PUT – заменить полностью (иногда создать по известному URI)

«Перепиши все с нуля». Полная замена ресурса по известному адресу. В некоторых API PUT может создать ресурс, если его нет (клиент указывает URI). Если не поддерживается, ожидайте 405/409. Метод идемпотентный².

Пример: PUT /orders/105 – заменить заказ 105 (или создать, если это оговорено контрактом).

PATCH – обновить частично

«Подправь, не трогая остальное». Меняет только указанные поля. Формат частичных изменений фиксируйте в контракте: application/merge-patch+json или application/json-patch+json.

Пример: PATCH /orders/105 – изменить только статус заказа.

DELETE – удалить

«Уберите это из системы». Поведение зависит от контракта: часто используется soft delete (пометка об удалении, аудит/логи сохраняются). Метод идемпотентный.

Пример: DELETE /orders/105 – отменить заказ 105.

Свойства методов:

• Безопасные (не меняют состояние): GET, HEAD, OPTIONS.

• Идемпотентные (повтор не меняет результат): GET, PUT, DELETE, HEAD, OPTIONS.

• POST – не идемпотентен; PATCH – идемпотентность не гарантируется.

Совет героя
Всегда выбирай метод по сути действия.

Если создаешь – POST, читаешь – GET, вносишь точечные правки – PATCH, заменяешь все – PUT (и помни: в некоторых API метод PUT создает ресурс с указанным тобой ID, если его еще нет), удаляешь – DELETE. Такой подход делает твой запрос не только технически корректным, но и «читаемым» как чистый текст на языке API.

Подходы и технологии интеграции

HTTP-методы определяют, что мы делаем с ресурсами, а архитектурный стиль API – как это взаимодействие устроено. У каждого стиля есть свои правила, структура запросов и способы передачи данных.

Важно: ниже перечислены разные сущности – стиль (REST), протокол (SOAP), язык запросов (GraphQL), RPC – фреймворк (gRPC), расширение REST (OData) и канал для real-time (WebSockets).

🔸 REST (Representational State Transfer) – архитектурный стиль (чаще поверх HTTP) с моделированием ресурсов и семантикой методов (GET/POST/PUT/PATCH/DELETE).

🔸 SOAP (Simple Object Access Protocol) – протокол обмена сообщениями с жестким контрактом (WSDL), XML и расширениями безопасности (WS-Security).

🔸 GraphQL – язык запросов к API: клиент сам описывает, какие поля и в каком объеме нужны; один эндпоинт — гибкие выборки.

🔸 gRPC – RPC-фреймворк (обычно HTTP/2 + Protocol Buffers) для быстрых двоичных вызовов между сервисами.

🔸 OData (Open Data Protocol) – спецификация поверх REST: унифицированные query-параметры ($filter, $select, $orderby, пагинация и т.д.).

🔸 WebSockets – двусторонний канал связи в реальном времени; это транспорт, а не стиль API (поверх него уже строят протоколы/события).

Мы подробно разберем REST и SOAP, так как они чаще всего встречаются в корпоративных проектах и при интеграциях между сервисами.

REST (Representational State Transfer)

REST – это не технология и не волшебный фреймворк, а стиль общения с API, где все держится на простых и понятных правилах. Если провести аналогию, REST – как меню в хорошем ресторане: ты говоришь «принесите суп», а тебе не приносят котлету, потому что правила заказа однозначны.

🟡 Ключевые особенности:

Stateless – сервер не хранит клиентское состояние сессии между запросами; весь контекст передается каждый раз (заголовки/тело/токен). Состояние ресурсов при этом хранится на сервере.
Использует «пять глаголов» HTTP – GET, POST, PUT, PATCH, DELETE. Тут все предсказуемо: смотришь – GET, создаешь – POST, переписываешь все – PUT, подправляешь чуть-чуть – PATCH, удаляешь – DELETE.
Чаще всего общается в формате JSON (иногда XML, но это как архаичный «привет» от 2000-х).
Легко встраивается в любую архитектуру – от микросервисов до монолитов, если разработчики договорились о правилах.

➕ Плюсы:

Простота – читается, как инструкция на понятном языке, а не как свиток древнего ордена программистов.
Гибкость – можно спокойно добавлять новые методы, поля и ресурсы, не разрушая старое.
Кроссплатформенность – REST не интересует, на чем ты пишешь сервер или клиент, лишь бы говорили на одном протоколе.

➖ Минусы:

– Нет жесткого стандарта: один разработчик назовет метод /getAllUsers, другой – /users, а ты потом ищи, кто из них был прав.

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

– Если API плохо спроектирован, предсказуемость REST превращается в квест «угадай URL».

🔵 Чаще всего используется в:

🔹 Веб- и мобильных приложениях.

🔹 Публичных API (Google, GitHub, X/Twitter).

🔹 Интеграциях между современными сервисами, где ценится скорость разработки и понятность.

SOAP (Simple Object Access Protocol)

SOAP – старший брат REST. Он не просто «разговаривает» с сервисами, а делает это по уставу. Представь отдел, где все по регламенту: каждый документ – в XML, все подписи проверены, и если печать стоит не в том углу – вернут с пометкой «Исправить».

🟡 Ключевые особенности:

Сообщения только в XML (без вольностей).
Жесткая структура <Envelope> с секциями <Header> и <Body> – все должно быть на своих местах.
Контракты описаны в WSDL (Web Services Description Language) – это как официальный документ, что можно делать, а что нельзя.
Поддерживает разные транспорты: HTTP(S), SMTP, FTP.
Имеет встроенные механизмы безопасности (WS-Security) – подписи, шифрование, токены.

➕ Плюсы:

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

➖ Минусы:

– Громоздкий по сравнению с REST – передать «Привет» иногда выходит на пару сотен строк XML.

– Отладка и тестирование требуют больше усилий.

– Любое изменение в контракте – отдельный проект с согласованиями.

🔵 Чаще всего используется в:

🔹 Банках и финансовых системах.

🔹 Интеграциях с государственными сервисами и реестрами.

🔹 Старых ERP и CRM, где REST еще не внедрили (и не факт, что внедрят).

Форматы данных

Когда системы общаются, они не кидаются друг в друга скриншотами или голосовыми – они обмениваются структурированными данными. Чтобы не было «испорченного телефона», стороны договариваются о формате.

JSON (JavaScript Object Notation)

Сегодняшний любимчик API. Почему его любят:

Компактный, ничего лишнего.
Читаемый, понятен и человеку, и машине.
Простой, ключ, значение, запятая, скобка – и все счастливы.

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

XML (eXtensible Markup Language)

Был безусловным лидером, когда интернет еще загружался по модему. Сегодня – как солидный нотариус: иногда медленнее, зато строго и надежно.

Почему до сих пор используют? Потому что:

Гибкий – легко описать сложные вложенные структуры.
Формальный – все четко по тегам.
Надежный м в банках и госуслугах доверяют именно ему.

Замечание героя: XML – это как отправить письмо в конверте с гербовой печатью: надежно, но распаковать чуть сложнее.

Как выбрать формат

В 90% случаев – JSON (цифра не из ГОСТа, но по проектам обычно так). Но правильный выбор – тот, который ждет сервер: смотри Content-Type в документации и указывай Accept в запросе.

Дальше разберем структуру REST-запроса и ответа как наиболее распространенный способ обмена данными по HTTP.

Структура REST-запроса и ответа

Любой запрос к API – как официальное письмо: есть адрес, способ доставки, служебные пометки и, если нужно, вложение. Разница в том, что тут все в «техническом костюме» – строгом и понятном машине. Адрес, заголовки и аккуратно упакованный контент (JSON/XML) лежат по местам, как в идеальном архиве. Из чего состоит запрос?

1. URL – точный адрес ресурса, к которому «стучимся».

Пример: https://api.jams.com/orders. Ошибешься буквой – попадешь в другой район (или получишь 404).

2. Метод (HTTP-метод) – «глагол» запроса:

GET – «Покажите, что у вас есть». Обычно без тела; формально тело допустимо, но почти всегда игнорируется (в практике не используем).
POST – «Создайте вот это». Всегда с телом запроса.
PUT – «Замените все целиком». Передаем полный набор данных.
PATCH – «Подправьте только вот это». Передаем изменяемые поля.
DELETE – «Уберите это». Обычно без тела; идентификатор — в URL.

3. Заголовки (Headers) – служебные записки для сервера:

Content-Type: application/json – «Данные пришли в JSON». Ставим только когда есть тело (POST/PUT/PATCH).

Для частичных обновлений лучше точнее: application/merge-patch+json или application/json-patch+json.

Accept: application/json – «И ответ, пожалуйста, в JSON».

Authorization: Bearer <token> – «Вот мой пропуск».

4. Тело (Body) – содержимое, которое передаем (POST/PUT/PATCH).

Content-Type ставим, когда есть тело.

Accept чтобы зафиксировать формат ответа (рекомендуется для JSON-API).

Authorization: Bearer <token>, если эндпоинт защищен (почти всегда в проде).

Ожидаемый ответ

201 Created + Location: <URI нового ресурса>; тело опционально.

204 No Content, успех без тела (часто для DELETE/PUT).

Для чтения/обновления с телом – обычно 200 OK (Content-Type: application/json). Остальные случаи см. в таблицк кодов ниже. Основные группы кодов.

Совет героя

Слушай не только, что система отвечает, но и на какой ноте. Три цифры в статус-строке – мимика собеседника. Иногда полезно отправить «кривой» запрос, чтобы понять, как система ведет себя на ошибках.

Сервер всегда отвечает не только данными, но и статус-кодом – трехзначным числом, которое мгновенно дает понять, успех это или провал.

Это язык вежливости между клиентом (мы) и сервером (система):

🔸 Клиент отправляет запрос.

🔸 Сервер принимает, обрабатывает и возвращает данные + код.

🔸 По коду можно даже без чтения тела понять, все ли прошло нормально.

Совет героя: Когда говоришь с системой, слушай не только, что она пишет, но и на какой ноте отвечает. Эти три цифры в начале ответа – как выражение лица собеседника. И не бойся иногда специально задать «неудобный вопрос» (отправить кривой запрос), чтобы понять, как система реагирует на стресс. Это пригодится, когда дорога станет сложнее.

Заголовки, параметры, аутентификация и авторизация

Любой API-запрос – как работа с фондом в научной библиотеке. Просто «дайте почитать» не прокатит: нужно указать шифр (куда идем), поставить фильтры (с какими условиями), показать читательский билет (аутентификация), иметь доступ к спецфонду (авторизация) и правильно заполнить заявку (headers + body).

Параметры пути (Path params) – инвентарный шифр экземпляра

Вшиваются в URL.
Когда обращаемся к конкретной единице фонда.
Пример: /books/978-5-4461-0923-4 или /loans/105 – «экземпляр/выдача №105».
В спеках: /books/{isbn}, /loans/{loan_id}.
Значения URL – кодируем; если внутри встречается /, кодируем как %2F.

Параметры строки запроса (Query params) – каталогизация и отбор

Начинаются после ?, пары разделяются &.
Для фильтрации/сортировки/пагинации/выбора полей.
Пример: /books?author=Тарг&year=2024&limit=10 — «по автору, за 2024, не больше 10».
Значения URL – кодируем (процентное кодирование: пробел → %20, кириллица → %D0…).
Секреты в query не кладем – попадают в логи и историю.

Заголовки (Headers) – «бланк заявки» и служебные пометки

Передаются отдельно от URL. Частые:

Content-Type: application/json – «заявка в JSON» (ставим, когда есть тело: POST/PUT/PATCH).
Accept: application/json – «верните карточку фонда в JSON».
Authorization: Bearer <token> – «читательский билет».

Для PATCH лучше точный тип: application/merge-patch+json или application/json-patch+json.

Тело (Body) – сама «заявка»

🔹 В PATCH – только изменяемые поля (например, return_date, status).

🔹 В PUT – полная карточка ресурса/выдачи.

🔹 Даты – ISO-8601 (YYYY-MM-DD или 2025-08-15T12:00:00Z).

🔹 Единый стиль ключей по всему API (например, snake_case).

Аутентификация (кто вы) – проверка читательского билета

Basic <base64(login:password)> – не шифрование, только по HTTPS.

Bearer <token> (часто JWT) – никогда не в URL.

API-ключ – лучше заголовком (X-API-Key: <key>), не в query.

Авторизация (что вам можно) – доступ к «спецфонду»

Роли/права (RBAC), scopes/claims в токене. Коды:

🔸 401 Unauthorized — билета нет/просрочен (не аутентифицированы).

🔸 403 Forbidden — билет есть, но спецфонд недоступен (прав недостаточно).

Сигналы на табло (статусы ответа)

— 200 OK все нашлось/обновилось, карточка внутри.

— 201 Created + Location – создана новая заявка/бронь.

— 204 No Content – действие выполнено, но без тела (часто для DELETE/PUT).

— 409 Conflict – конфликт брони/дубликат.

— 415 Unsupported Media Type – «бланк» в неверном формате (Content-Type).

— 422 Unprocessable Entity – заявка валидна формально, но поля некорректны по бизнес-правилам.

Совет героя:

Path params – «где именно искать».

Query params – «с какими условиями».

Headers – «как обрабатывать и кто прислал».

Инструменты для работы с API

API – это переговорная между системами. Никто не спорит, никто не хлопает дверьми, но каждое слово должно быть на своем месте. Чтобы этот «дипломатический прием» прошел без накладок, у аналитика есть свой чемоданчик инструментов.

Postman – швейцарский нож API (https://www.postman.com)

Отправляет любые запросы (GET, POST, PUT, PATCH, DELETE), хранит коллекции, переключает окружения, запускает автотесты и подключает их в CI/CD. Главное не путать тест с продом, иначе легенда о твоем DELETE будет жить в корпоративных чатах вечно.

Swagger / OpenAPI – интерактивная карта (swagger.io)

Вместо дорог – эндпоинты. Видно все: методы, параметры, примеры. Можно запустить запрос прямо из браузера. Если карты нет-попроси разработчиков сгенерировать: 10 минут работы, а экономит часы мучений.

curl – полевой телефон (curl.se)

Никаких красивых кнопок, только команда и честный ответ сервера. Работает, когда Postman под рукой нет, а проверить надо «еще вчера».

Mock-серверы – репетиция перед премьерой

Когда бэкенд спит, а фронт уже готов. Моки позволяют прогнать сценарии до реальной интеграции.

Инструменты: Mockoon (mockoon.com), Beeceptor (beeceptor.com), Mocky.io (mocky.io).

Визуализация API-увидеть весь спектакль

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

Инструменты: Lucidchart (lucidchart.com), Draw.io (app.diagrams.net), Miro (miro.com), Mermaid (mermaid.js.org).

Бонус-набор – Insomnia (insomnia.rest) как легкая альтернатива Postman, Paw (paw.cloud) для macOS, JSON Formatter (jsonformatter.org) превращает «портянку» JSON в аккуратную структуру.

Нейросети и умные помощники

ChatGPT или аналог (LLM-помощник) + OpenAPI-спека – быстрый способ сгенерировать примеры и автотесты. Apidog (apidog.com) тестирование, документация и визуализация в одном. Stoplight Studio (stoplight.io) быстрая визуальная правка OpenAPI.

В этот момент наш герой слышит систему по-настоящему. Ее голос больше не кажется набором случайных сигналов – это четкие реплики на понятном языке, где каждое слово – метод, каждый намек – параметр, а пауза – статус-код. Он больше не стучит в закрытые двери, а точно знает, какой ключ подойдет – Path, Query, заголовок или токен.

И вот на его теле начинают проступать тонкие, уверенные полоски-маршруты, по которым теперь бегут данные. Каждая полоса ведет от запроса к ответу, от клиента к серверу, от идеи к результату. Эти линии похожи на дороги, нанесенные на карту, только теперь карта – он сам. Это не просто рисунок – это карта его новых умений, выведенная прямо на коже, как метка того, что он стал частью диалога между системами.

Теперь архитектура для него – не только карта и план, но и живой диалог, в котором он умеет спросить, уточнить, изменить и получить ответ. Он готов к интеграциям, как дипломат, который знает, когда сказать твердое «DELETE», а когда мягкое «PATCH».

Обсудить проект

Совет героя

Базовое знакомство с API у нас состоялось. Мы разобрали, как строится запрос и ответ, где искать параметры и заголовки, чем отличается путь от строки запроса, и какие инструменты помогают держать этот «дипломатический» диалог систем в четкой структуре.

Если хотите пойти глубже, я рекомендую курс по API от компании «Лаборатория качества». На нем вы разберете API так, что перестанете путать Path и Query даже в три часа ночи, изучите форматы данных (JSON, XML и другие), разберете реальные кейсы и отработаете все на практике. Вдобавок вас познакомят с ключевыми инструментами: Postman, Swagger, curl, мок-серверами, визуализацией и даже с полезными AI-помощниками – так, чтобы потом использовать их уверенно и без лишней паники.

API (Application Programming Interface) – это интерфейс, который позволяет осуществлять взаимодействие между программами. Если человек общается с приложением через кнопки и диалоги (пользовательский интерфейс, UI), то программы обмениваются информацией друг с другом через API. ↩︎
Идемпотентность в контексте бизнес-анализа, как и в разработке ПО, означает свойство операции, при котором повторное выполнение с теми же входными данными не меняет состояние системы больше, чем однократное выполнение. Другими словами, если операция идемпотентна, повторное ее применение не должно приводить к дополнительным изменениям или побочным эффектам, кроме случаев, когда это явно предусмотрено. ↩︎