С нуля: что такое API на самом деле
API — это контракт, по которому две программы говорят друг с другом. Это карта «с нуля» и восемь слов, которые остальной трек считает знакомыми до начала senior-юнитов.
Ты открываешь приложение погоды и видишь прогноз на сегодня. Ты не писал погодные данные — никто не ожидает, что ты владеешь спутниками. Где-то за кулисами твоё приложение отправило вопрос компьютеру метеокомпании, а тот компьютер прислал ответ. Ни одной программе не важно, на каком языке написана другая, на какой ОС работает или где в мире находится. Они просто следуют общему соглашению — как спрашивать и как отвечать. Это соглашение и есть API. Всё в этом треке — REST, статус-коды, пагинация, GraphQL, gRPC, rate limiting — это детали, построенные поверх одной идеи. Этот урок — карта перед юнитами.
Единственная проблема, которую решают API
Когда ты добавляешь кнопку оплаты, встраиваешь карту или входишь через Google, чужой компьютер делает работу за тебя — и ему ничего не известно о твоей кодовой базе. API — это то, как всё это работает без хаоса.
Любому нетривиальному приложению нужны данные или функциональность, которые оно не строило само: обработка платежей, тайлы карт, аутентификация, котировки акций, перевод. Без общего соглашения каждой паре программ пришлось бы изобретать свой язык общения с нуля. API решает это, публикуя стабильный, задокументированный контракт: «пришли мне сообщение такой формы, и я всегда отвечу вот такой формой». Вызывающей стороне не нужно знать, как другая сторона работает внутри, — только что спросить и что ожидать в ответ. Это разделение и делает интернет составным: миллионы программ говорят с миллионами других, каждая знает только поверхность того, что вызывает.
Всё остальное в этом треке — детали поверх одной идеи: публикуй стабильный контракт, затем соблюдай его.
Восемь слов, которые остальной трек считает знакомыми
Senior-уроки дальше используют эти термины, не останавливаясь на определениях. Вот они, по одному предложению — что это и зачем оно.
| Слово | Что это | Зачем оно |
|---|---|---|
| API | Опубликованный контракт, описывающий, как две программы могут говорить. | Чтобы каждая сторона могла меняться независимо, пока соблюдает контракт. |
| Endpoint (эндпоинт) | Конкретный URL, представляющий один ресурс или действие (например, /users/42). | Чтобы у каждой возможности был стабильный адрес, по которому вызывают. |
| HTTP-метод | Глагол (GET, POST, PUT, PATCH, DELETE), говорящий, что делать по эндпоинту. | Чтобы один URL означал «читать», «создать», «обновить» или «удалить» в зависимости от глагола. |
| Тело запроса | Данные, которые вызывающая сторона отправляет с POST или PUT (обычно JSON). | Чтобы сервер знал, что создать или как обновить, а не догадывался. |
| Тело ответа | Данные, которые возвращает сервер (обычно JSON). | Чтобы вызывающая сторона получила результат предсказуемой формы. |
| JSON | Текстовый формат для структурированных данных: ключи, значения, массивы, объекты. | Чтобы любой язык мог читать и писать данные без специального парсера. |
| Статус-код | Трёхзначное число (200, 404, 500 …), которое сервер добавляет к каждому ответу. | Чтобы вызывающая сторона сразу знала, удался запрос или почему нет. |
| Ресурс | Вещь, которую открывает API, — пользователь, заказ, товар, сообщение. | Чтобы API строился вокруг стабильных существительных, а не серверных операций. |
Как они складываются вместе
Прочитанные по порядку, слова рассказывают одну историю: клиент выбирает эндпоинт (URL, называющий ресурс), выбирает HTTP-метод (что делать) и опционально посылает тело запроса с данными. Сервер выполняет работу, затем возвращает тело ответа — обычно JSON — плюс статус-код, говорящий, получилось ли. Обе стороны заранее договорились, как выглядят эти формы: это соглашение и есть контракт API. Этот абзац — весь трек в миниатюре; каждый следующий юнит увеличивает один из кусков.
▸Почему это работает
Зачем всему этому формальный контракт? Потому что программы меняются. Команда бэкенда может переписать свою базу данных с нуля, команда фронтенда может перепроектировать весь UI, — и пока обе стороны говорят по одному API, ничего не ломается у другой. Без этого контракта каждое изменение с одной стороны рискует молча поломать другую. Контракт — это не бюрократия, это то, что позволяет двум командам двигаться независимо и быстро.
Это не нужно зубрить
Две честные ремарки перед юнитами. Первая: никто не держит всё это в голове сразу в первый день — ты встретишь каждое слово снова, в глубине, в своём юните, и тогда оно уляжется. Эта страница — вешалка, на которую вешать детали, а не экзамен. Вторая: не каждый API использует каждое слово одинаково. REST интенсивно использует ресурсы и HTTP-методы; GraphQL игнорирует большинство HTTP-методов и использует один эндпоинт; gRPC вовсе обходится без JSON. Трек учит полному ландшафту, потому что этого требуют реальные системы, — но «понять концепцию, затем научиться, как каждый стиль её применяет» и есть senior-инстинкт.
Для чего нужен HTTP-статус-код?
Расставь шаги одного API-вызова, от клиента до ответа:
- 1 Клиент выбирает эндпоинт (URL + ресурс) и HTTP-метод
- 2 Клиент отправляет запрос с опциональным JSON-телом
- 3 Сервер обрабатывает запрос и формирует ответ
- 4 Сервер возвращает JSON-тело и статус-код
- 01В одном дыхании: что такое API и почему важен контракт?
- 02Проследи один полный API-вызов, называя каждую часть.
API — это одна идея с кучей навешанных деталей: публикуй контракт, говорящий, как спрашивать и как отвечать, и соблюдай его, чтобы обе стороны могли меняться независимо и не ломать друг друга. Половина запроса — это метод (GET, POST, PUT, PATCH, DELETE), направленный к эндпоинту (URL, называющему ресурс), с опциональным JSON-телом, несущим данные. Половина ответа — JSON-тело плюс статус-код, говорящий, получилось ли. JSON — универсальный формат данных, на котором обе стороны сходятся, потому что любой язык может его читать без специального парсера. Эндпоинт называет ресурс — существительное вроде пользователя, заказа или товара, — а не серверную операцию, чтобы API оставался стабильным при изменении внутренностей. Тебе не нужно держать все восемь слов сразу — у каждого впереди свой юнит. Теперь, когда встретишь «API вернул 404» или «пошли POST с JSON-телом», ты будешь знать, какая именно часть контракта нарушена и куда смотреть дальше.
Что-то непонятно?
Задай вопрос по этому уроку. Вопросы анонимны и попадают напрямую автору — урок станет лучше.
Примени это
Примени этот урок в реальном проекте.