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

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

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

Что такое API и зачем оно аналитику

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

Интерфейс может связывать экран сайта с сервером, два сервиса внутри компании или приложение с внешней системой. API не обязательно работает через HTTP и не обязательно следует стилю REST. Ниже мы разбираем распространённый частный случай — HTTP API в стиле REST, где запросы обращаются к ресурсам, например к заказам.

Для аналитика это часть описания поведения системы. Фраза «передать заказ на сервер» оставляет слишком много вопросов. Какие поля обязательны? Может ли один пользователь посмотреть заказ другого? Что показать, если товара уже нет? Ответы нужны разработчику, тестировщику и команде соседнего сервиса.

Клиент, сервер, запрос и ответ: один заказ от кнопки до номера

Допустим, покупатель нажал «Оформить заказ». В этом примере клиент — приложение магазина в браузере. Сервер — сервис заказов, который принимает запрос и решает, можно ли создать заказ. Эти слова описывают роли в конкретном обмене: один и тот же сервис может быть сервером для приложения и клиентом для другого сервиса.

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

POST /orders HTTP/1.1
Host: api.example.com
Authorization: Bearer <токен>
Content-Type: application/json

{
  "productId": "book-42",
  "quantity": 1
}

Здесь POST обозначает действие над коллекцией заказов, /orders — адрес ресурса, Authorization передаёт учётные данные по схеме Bearer, а Content-Type сообщает формат тела запроса. api.example.com и <токен> — условные значения; настоящий токен нельзя помещать в публичный пример.

Если заказ создан, сервер может ответить так:

HTTP/1.1 201 Created
Location: /orders/ord-204
Content-Type: application/json

{
  "id": "ord-204",
  "productId": "book-42",
  "quantity": 1,
  "status": "created"
}

Код 201 Created говорит об успешном создании ресурса, Location указывает его адрес, а тело содержит данные нового заказа. В конкретном API состав полей может быть другим — его фиксируют в документации.

Теперь клиент может запросить заказ по адресу GET /orders/ord-204. Сервер вернёт его представление, например с кодом 200 OK. Так экран узнает актуальный статус без прямого доступа к базе данных сервиса заказов.

Что такое JSON в этом примере

JSON — текстовый формат представления данных. Запись в фигурных скобках — объект с парами «имя: значение». В примере productId — строка, quantity — число. JSON также допускает логические значения true и false, null, вложенные объекты и массивы. Имена полей и их смысл определяются контрактом API.

Важно различать синтаксис и правило бизнеса. Запись "quantity": -3 может быть допустимым JSON, но недопустимым количеством товара. Аналитик должен явно описать проверку: например, целое число от 1 до 99. Серверу нужен согласованный ответ на нарушение этого правила, а интерфейсу — понятное сообщение для покупателя.

HTTP-методы и статусы: что они сообщают

Для нашего HTTP API полезно запомнить несколько методов. Это значения протокола, а не произвольные названия команд.

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

Статус ответа помогает понять итог запроса:

Например, если покупатель отправил quantity: -3, команда может договориться о 400 и теле ошибки с полем quantity. Если он запрашивает чужой заказ, ответ зависит от политики доступа конкретного API. Нельзя заранее обещать один и тот же статус для всех систем.

Авторизация: кто вправе сделать запрос

В нашем примере клиент передаёт токен в заголовке Authorization. Сервер использует его, чтобы определить, от чьего имени поступил запрос. Затем проверяет права: может ли этот пользователь создать заказ или посмотреть заказ ord-204.

Аутентификация отвечает на вопрос «кто обращается?», авторизация — «что ему разрешено?». Токен не заменяет проверку прав на конкретный заказ. Аналитику стоит зафиксировать, кто выдаёт токен, какие операции доступны разным ролям, что происходит после истечения срока действия и какой ответ получает клиент при отказе. Секреты и реальные токены в документацию и скриншоты не вставляют.

Контракт API: о чём нужно договориться до разработки

Контракт API — описание правил обмена между сторонами. Для нашего заказа минимальный список выглядит так:

1. Описать операцию: POST /orders, её назначение и момент вызова.
2. Перечислить входные данные: productId и quantity, типы, обязательность и ограничения.
3. Зафиксировать успешный результат: статус 201, поля ответа и адрес созданного заказа.
4. Разобрать ошибки: неверное количество, неизвестный товар, отсутствие доступа, повторный запрос.
5. Уточнить права: кто создаёт и читает заказы, как сервер проверяет принадлежность заказа.
6. Согласовать поведение при повторе и сбое: может ли повторный POST создать второй заказ и как клиент узнает итог, если ответ потерялся.

Контракт можно оформить текстом и примерами, а для HTTP API описать машинно читаемым форматом OpenAPI. В нём фиксируют пути и операции, параметры, тела запросов, ответы и схемы безопасности. Название Swagger часто встречается рядом с OpenAPI; при чтении документации важнее найти конкретную операцию и проверить все сценарии, чем запомнить название инструмента.

Какие вопросы задаёт системный аналитик

Если вам поручили «подключить оформление заказов», начните не с рисования стрелки между системами, а с вопросов:

• Кто создаёт productId и кто отвечает за его актуальность?
• Что делать, если товар исчез между открытием карточки и оформлением?
• Какой ответ вернётся при неверном количестве и что покажет интерфейс?
• Как предотвратить два заказа, если клиент повторит запрос после сетевого сбоя?
• Где проходит граница доступа: кто может читать и менять конкретный заказ?

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

Как начать изучать API, если вы новичок

Возьмите одну операцию из документации и пройдите её в таком порядке: найдите метод и адрес, выпишите обязательные поля, прочитайте пример успешного ответа, затем проверьте ошибки и правила доступа. Для самопроверки попробуйте словами объяснить, что увидит пользователь при каждом результате. Если это неясно, документация или требования ещё неполные.

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

В программе Prosystalent есть отдельные блоки по форматам данных, интеграциям, REST API и тестированию API. Обучение длится 6 недель, затем команда сопровождает поиск работы. Предоплата — 0 ₽; после официального трудоустройства предусмотрена оплата 20% от дохода в течение 12 месяцев по условиям договора. Посмотрите условия оплаты и оставьте заявку, если хотите обсудить программу и свой старт.

Частые вопросы