Что такое API простыми словами: официант в ресторане

Вячеслав Степанов — проджект-менеджер, ментор · 7 октября 2026

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

Если видео не открывается — смотри на YouTube (может понадобиться VPN).

Что такое API

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

Важно: API — это не отдельная программа и не сайт, а договорённость. В ней записано, какие просьбы можно отправлять, по какому адресу, в каком виде и что придёт в ответ. Разработчики называют такую договорённость контрактом: пока обе стороны его соблюдают, всё работает.

Аналогия с официантом

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

В IT-продукте всё так же:

• Гость — фронтенд: то, что пользователь видит в браузере или приложении. Сам в базу данных он ходить не может.
• Кухня — бэкенд и база данных: программа на сервере, которая хранит данные, считает, отправляет письма и сообщения.
• Официант — API: принимает просьбы фронтенда по строгим правилам и возвращает результат.

А меню — это список того, что можно заказать. В API ему соответствует список эндпоинтов, о них — ниже. Подробнее о том, кто делает фронтенд и бэкенд, — в статье про роли в IT-команде.

Где API встречается каждый день

• Прогноз погоды в телефоне. Приложение не измеряет погоду само — оно запрашивает данные у метеосервиса через его API.
• Вход через Яндекс ID или VK ID. Сайт через API спрашивает у Яндекса или VK, кто ты, и получает подтверждение.
• Оплата на сайте. Магазин через API банка создаёт платёж и узнаёт, прошла ли оплата.
• Уведомления в Telegram. Сервис отправляет сообщение через API Telegram.

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

Эндпоинт: одна конкретная просьба

Официант умеет принимать разные просьбы: принести меню, взять заказ, изменить его, принести счёт. В API каждая такая просьба — отдельный эндпоинт (endpoint). Это одна операция API, у которой есть:

• адрес — куда обращаться, например /api/students;
• метод — что сделать по этому адресу: прочитать, создать, изменить или удалить.

Один эндпоинт — одно чёткое действие. Как одна позиция в меню: точное название блюда, а не «что-нибудь съедобное».

HTTP-методы: что мы просим сделать

Есть ещё PATCH — частичное изменение, но проджекту он встречается редко. Простое правило: если операция читает данные — GET, создаёт запись — POST, меняет — PUT, удаляет — DELETE.

Запрос и ответ

Запрос (request) — то, что фронтенд отправляет серверу. Данные обычно передают в формате JSON — это просто набор пар «поле: значение». Например, фронтенд просит отправить ученику напоминание об оплате:

POST /api/reminders

{
  "student_id": 42,
  "channel": "TELEGRAM"
}

Ответ (response) — то, что сервер возвращает. Тоже JSON, плюс код ответа из трёх цифр, который сразу говорит, получилось или нет:

200 OK

{
  "sent_at": "2025-07-31T14:22:00Z"
}

Коды делятся на группы по первой цифре (подробная шпаргалка — в статье про HTTP-коды):

• 2xx — успех. 200 OK — всё получилось, 201 Created — запись создана.
• 4xx — ошибка в запросе. «Ты неправильно попросил»: 400 — запрос составлен неверно, 401 — пользователь не вошёл в систему, 403 — вошёл, но прав нет, 404 — такого нет, 409 — конфликт, например напоминание уже отправляли сегодня.
• 5xx — ошибка на сервере. «У меня сломалось»: 500 — внутренняя ошибка, 502 — не отвечает внешний сервис, например Telegram.

Для проджекта коды — быстрый способ понять, на чьей стороне проблема. 4xx — обычно что-то не так с запросом или правами, 5xx — что-то упало на сервере.

Что такое REST API

В вакансиях и документации часто пишут «REST API». REST — самый распространённый стиль построения веб-API. Его описал американский учёный Рой Филдинг в диссертации 2000 года. Если упростить, в REST у каждого вида данных свой адрес (/api/students, /api/lessons), а что с ними делать, задают HTTP-методы — те самые GET, POST, PUT и DELETE. Все примеры в этой статье — в стиле REST.

Описание API команды обычно хранят в документации — часто в формате Swagger: это страница, где перечислены все эндпоинты с примерами запросов и ответов. А «потрогать» API руками без кода можно в программе Postman: в ней отправляют запрос и смотрят, что вернул сервер.

Зачем API проджект-менеджеру

• Читать и писать системную аналитику. В документе по новой фиче есть раздел про API: эндпоинты, поля, ответы и ошибки. Проджект должен понимать его, а в небольших командах — уметь написать черновик сам.
• Прикидывать объём работы. Полезное правило: одно действие пользователя — один эндпоинт. Открыл экран — системе нужно принести данные. Нажал кнопку — что-то сделать. Выпиши действия из описания фичи — и получишь черновой список эндпоинтов, а с ним понимание масштаба.
• Видеть зависимости. Фронтенду нужен готовый эндпоинт бэкенда. Если бэкенд не успевает, фронтенд работает на заглушках, а проджект планирует порядок задач с учётом этой связи.
• Разбираться в сбоях. «Пользователи видят ошибку при оплате» — проджект смотрит, какой эндпоинт и какой код ответа, и сразу понимает, к кому идти.
• Беречь контракт. Если бэкенд переименует поле в ответе, фронтенд сломается. Изменения API проджект согласует между командами заранее.

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

• Думать, что API — это отдельная программа. API — договорённость о том, как программы общаются. Лекарство — держать в голове аналогию с официантом и меню.
• Пустой список считать ошибкой. Если должников нет, сервер честно возвращает пустой список с кодом 200, а не 404. Лекарство — различать «ничего не нашлось» и «запрос сломался».
• Менять поля «по-тихому». Бэкенд переименовал поле, фронтенд упал на проде. Лекарство — изменения контракта согласовывают и записывают в документации.
• Решать технические вопросы за команду. Где сортировать список — на фронтенде или на сервере — решает техлид. Лекарство — проджект записывает такие вопросы в открытые и приносит их техлиду.
• Бояться API. Новичку кажется, что это только для программистов. Лекарство — один раз описать эндпоинт для простой фичи: дальше становится понятно.

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