Что такое…

Что такое HTTP-заголовки — и почему ключ едет там, а не в ссылке

Иллюстрация: посылка с открытыми бирками на верёвке и одной, запечатанной сургучом

Смотри, странная на первый взгляд штука: почти каждый API просит передавать ключ заголовком, а не просто дописать его в ссылку. Технически второе проще — и работает. Но так почти никто не делает, и причина неожиданно бытовая: ссылки записываются. В логи сервера, в историю браузера, в аналитику. Заголовки — нет.

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

Что это такое в одной фразе

Заголовки — это сопроводительная записка к запросу, отдельно от самого содержимого.

Представь посылку. На коробке написан адрес — это URL, куда едет запрос. Внутри лежит содержимое — это тело запроса. А сбоку наклеены бумажки: «хрупкое», «получатель — Иванов», «оплачено». Вот это и есть заголовки: не сам груз, а информация о грузе и об отправителе.

Формат простой до скуки — Имя: значение, по одной паре на строку:

Content-Type: application/json
Authorization: Bearer sk-abc123

Всё. Никакой магии. Просто список пометок, который сервер читает до того, как возьмётся за само содержимое.

Как выглядит живой запрос

Когда ты дёргаешь API из кода, целиком уходит примерно вот такое:

POST /v1/messages
Content-Type: application/json
Authorization: Bearer sk-abc123
Accept: application/json

{"text": "привет"}

Первая строка — что делаем и куда. Дальше — заголовки. Потом пустая строка, и после неё тело. Браузер, curl и твой код собирают ровно эту конструкцию, просто ты обычно её не видишь.

Открой в браузере DevTools → Network, ткни в любой запрос и найди вкладку Headers — там всё то же самое, только с человеческим оформлением. Это, кстати, первое место, куда стоит смотреть, когда «запрос вроде правильный, а не работает».

Почему ключ едет в заголовке, а не в ссылке

Теперь к неожиданной части. Ключ можно было бы отправить так: /v1/messages?key=sk-abc123. Сервер прочитает, всё сработает. Но у ссылки есть свойство, которого нет у заголовка: её везде сохраняют.

  • Веб-серверы пишут полный URL каждого запроса в свои логи. Ключ окажется в текстовом файле, который читают несколько человек.
  • Браузер кладёт адрес в историю и подставляет в автодополнение.
  • При переходе по ссылке адрес может уехать на чужой сайт в заголовке Referer.
  • Ссылку удобно скопировать и кинуть в чат — вместе с ключом.

Заголовок не попадает ни в историю, ни в адресную строку, и в логи по умолчанию не пишется. Отсюда правило: секрет — в заголовок, всё остальное — можно в ссылку. Это же объясняет, почему ключи не стоит хранить в коде фронтенда — заголовок скрывает ключ от логов, но не от того, кто открыл DevTools у себя в браузере.

Четыре заголовка, которые ты встретишь первыми

Content-Type — на каком языке написано тело. application/json значит «внутри JSON». Если не поставить или поставить не тот — сервер честно попробует прочитать JSON как обычный текст и вернёт ошибку разбора. Это причина №1 загадочных 400-х у новичков.

Authorization — кто ты. Обычно в форме Bearer твой_ключ. Забыл слово Bearer, лишний пробел, подставился undefined — и получаешь 401 «сервер тебя не узнал».

Accept — что ты хочешь получить в ответ. Говоришь application/json — сервер, который умеет и JSON, и XML, отдаст JSON.

User-Agent — чем прислали запрос: браузер, скрипт, бот. Некоторые сайты по нему отдают разное содержимое, а некоторые по нему же блокируют скрипты.

Заголовки ответа: сервер тоже пишет записку

Обмен двусторонний. Сервер отвечает своими заголовками, и они объясняют кучу вещей, которые иначе выглядят как мистика:

  • Content-Type — что он прислал. Браузер по нему решает, показать страницу или скачать файл.
  • Set-Cookie — «запомни вот это и присылай обратно». Так и работают куки.
  • Cache-Control — сколько времени ответ можно считать свежим. Отсюда растёт «я обновил сайт, а у пользователя старая версия».
  • Access-Control-Allow-Origin — кому из браузера можно к этому API. Нет заголовка — ловишь ошибку CORS.

Чем заголовок отличается от параметра в ссылке?

Параметр (?page=2) — часть адреса: он виден, сохраняется в истории и логах, его удобно скопировать. Заголовок едет рядом и нигде по умолчанию не остаётся. Поэтому в ссылку кладут то, что описывает какая именно страница нужна, а в заголовок — то, что описывает тебя и формат обмена.

Можно ли придумать свой заголовок?

Да, и так делают постоянно. Многие API ждут ключ в собственном заголовке вроде x-api-key. Правило одно: не угадывай формат, а открой документацию нужного API и сверь буквально — название, регистр не важен, а вот наличие слова Bearer очень даже.

Почему браузер не даёт поставить некоторые заголовки?

Часть заголовков браузер заполняет сам и запрещает трогать из JavaScript — например Host, Referer, реальный User-Agent. Иначе любая страница могла бы притвориться другим сайтом или другим браузером. Из кода на сервере таких ограничений нет — там ты хозяин всего запроса.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →