1. Роль заголовков: смысл, не красота
Если раньше вы видели headers как «какие-то строки, которые инструменты прячут в отдельной вкладке», то сейчас мы сделаем их нормальной частью мышления. Заголовки — это метаданные: они не являются самими данными ресурса, но говорят, как понимать запрос и ответ. И зачастую именно они решают, будет ли body разобран правильно, сможет ли клиент понять формат ответа и как клиенту продолжить работу после создания ресурса.
На уровне «скелета» HTTP-сообщение выглядит примерно так:
<start line> (request line или status line)
<header>: <value>
<header>: <value>
... ещё заголовки ...
<пустая строка>
<body> (может отсутствовать)Сравните два мира. В консольной программе мы обычно передаём данные «по проводу» напрямую: method(arg). Никому не нужно отдельно писать «аргумент — это строка в UTF‑8». В HTTP же всё передаётся как байты, и без метаданных обе стороны начинают гадать. Headers — это как наклейки на посылке: «СТЕКЛО», «ВЕРХ», «НЕ БРОСАТЬ», «ОТКРЫВАТЬ ЭТИМ КРАЕМ». Сама посылка — это body, но наклейки часто важнее, чем кажется.
И ещё один важный момент. Мы вчера и в первой половине дня говорили: статус-код — это отдельный слой смысла. Так вот, headers — такой же отдельный слой смысла. Не «украшение», а часть договора. Если статус и body говорят «я сделал то-то», headers часто отвечают на вопрос «в каком виде» и «что делать дальше».
2. Content-Type: что именно лежит в body
Content-Type — это заголовок, который отвечает на очень приземлённый вопрос: «в каком формате отправлено тело (body)». Причём это работает и для запроса, и для ответа. Если есть body, почти всегда должно быть ясно, что в нём: текст, JSON, бинарный файл, что-то ещё. Если body нет (например, GET без тела или 204 No Content), то и смысл Content-Type обычно пропадает.
Начнём с самой важной мысли: Content-Type — это не «что я хочу получить», а что я реально отправил. Если я отправил JSON, я так и пишу:
Content-Type: application/jsonЕсли я отправил обычный текст (например, очень учебный ответ /health в виде строки), это может быть:
Content-Type: text/plainВ живой разработке чаще всего вы будете встречать application/json (и почти всегда это будет ваш baseline для API), но полезно видеть и другие варианты — хотя бы чтобы не удивляться.
Мини-таблица «что чаще всего встретите»
| Формат body | Типичный Content-Type | Где часто бывает |
|---|---|---|
| JSON | application/json | почти любой backend API |
| Обычный текст | text/plain | простые health/debug ответы, прототипы |
| HTML | text/html | браузерные страницы (не про наш курс) |
Обратите внимание: мы ещё не изучали JSON как формат (это будет отдельный уровень), но это не мешает нам понимать роль заголовка. Даже если вы не знаете, что внутри, вы уже понимаете, что это «тип данных».
### Без Content-Type: всё разваливается
Представим, что клиент отправил POST с body, а сервер ждёт JSON. Если у клиента не указан Content-Type, серверу приходится угадывать. Иногда сервер попытается угадать, иногда откажется, иногда «съест» как текст и потом упадёт на парсинге. И в итоге вы получаете ситуацию: body есть, но смысла нет.
И наоборот, сервер может вернуть body, но если не укажет Content-Type, клиент не поймёт, чем его разбирать. Да, некоторые клиенты пытаются догадаться (по первым символам, по эвристикам, по «ну это же похоже на JSON»), но это плохая привычка. Контракт должен быть явным.
### Простой Java-пример
Пока мы ещё не пишем HTTP-клиент на Java и не поднимаем сервер, можно потренировать мышление «контрактом» прямо в ReadLaterApplication. Просто как аккуратную модель: какие headers у нас должны быть.
import java.util.Map;
public class ReadLaterApplication {
public static void main(String[] args) {
// Заголовки — это часть контракта: как понимать тело и что ожидать в ответ
Map<String, String> requestHeaders = Map.of(
"Content-Type", "application/json", // что именно мы отправили в body
"Accept", "application/json" // какой формат ответа мы хотим получить
);
// Читаем значения по имени заголовка — так же, как это делает реальный HTTP-стек
System.out.println(requestHeaders.get("Content-Type")); // application/json
System.out.println(requestHeaders.get("Accept")); // application/json
}
}Это не «настоящий HTTP», но это полезная дисциплина: вы начинаете видеть, что заголовки — это не случайный шум, а обязательные поля контракта.
### Тонкий, но важный нюанс: Content-Type уместен не всегда
Если вы делаете GET без тела, то Content-Type в запросе обычно не нужен. Он описывает тело запроса, а тела нет — описывать нечего. То же самое с ответом 204 No Content: там body отсутствует, значит, Content-Type как минимум бессмысленен. Некоторые сервера всё равно его ставят «по инерции», но в хорошем контракте такие детали стараются не плодить, чтобы не вводить клиента в заблуждение.
3. Accept: какой формат ответа ожидает клиент
Accept — почти зеркальная история, но ключевое слово здесь именно «ожидает». Если Content-Type говорит «вот в каком формате я отправил body», то Accept говорит «вот в каком формате я хочу получить body в ответ». То есть это заголовок запроса, который помогает серверу выбрать формат ответа, если сервер вообще умеет несколько форматов.
На практике в маленьком учебном API (и в большинстве реальных API тоже) формат обычно один — JSON. Но даже тогда Accept полезен как часть дисциплины и как явная договорённость: клиент не «надеется», а заявляет ожидание.
Типичный запрос чтения списка может выглядеть так:
GET /api/v1/reading-list HTTP/1.1
Accept: application/jsonТут нет body, поэтому Content-Type в запросе не нужен, зато Accept уместен: «сервер, пожалуйста, верни JSON».
### Accept не гарантирует, но договаривается
Важно понимать психологию этого заголовка. Accept — это не приказ в стиле «делай так, иначе я обижусь», а скорее «я так умею, мне так удобно». Если сервер не поддерживает указанный формат, он может вернуть другой (что плохо) или честно сообщить, что не может (в реальности для этого есть отдельные статусы, но сегодня мы не уходим в энциклопедию кодов).
В рамках нашего курса можно держать простое правило: клиент ставит Accept: application/json, сервер отвечает Content-Type: application/json. Это делает контракт читабельным и предсказуемым даже без глубоких теорий про «согласование представлений».
### Мини-ловушка новичка: Accept и Content-Type — разные стороны
Очень распространённая ошибка: думать, что Accept описывает тело запроса. Не описывает. Accept — это про ответ. В запросе про тело говорит только Content-Type.
Если запомнить в виде маленькой мнемоники, будет проще: Accept — это «я принимаю вот такие форматы» (то есть «могу съесть»), а Content-Type — «внутри вот это» (то есть «что вы мне принесли»).
### Java-пример: учебная модель
import java.util.LinkedHashMap;
import java.util.Map;
public class ReadLaterApplication {
public static void main(String[] args) {
// LinkedHashMap нужен здесь только ради стабильного порядка при выводе
Map<String, String> headers = new LinkedHashMap<>();
// Accept описывает то, какой формат ответа клиент умеет «переваривать»
headers.put("Accept", "application/json");
// Печатаем — просто чтобы визуально закрепить идею «заголовки как словарь»
System.out.println(headers); // {Accept=application/json}
}
}Тут мы используем LinkedHashMap, чтобы порядок выглядел стабильнее в выводе (это мелочь, но иногда приятно для мозга, который только начинает дружить с контрактами).
4. Location: адрес созданного ресурса
Location — это заголовок ответа, который чаще всего всплывает вместе с 201 Created. Его смысл очень практический: когда клиент создал новый ресурс (обычно через POST), сервер должен помочь клиенту понять, где этот ресурс теперь живёт. Не «где-то у вас в памяти», а по какому URI его можно получить.
В контексте нашего будущего ReadLater API это выглядит идеально. Клиент отправляет POST /api/v1/reading-list — «создай мне элемент списка чтения». Сервер создаёт, присваивает id, и в ответе говорит: «создано, вот адрес нового ресурса».
Пример (в виде «сырого» ответа):
HTTP/1.1 201 Created
Location: /api/v1/reading-list/43
Content-Type: application/json
{"id":43,"title":"Clean Code","author":"Robert C. Martin","status":"PLANNED"}Мы пока не разбираем JSON-структуру — нам важно другое: клиент может сразу взять Location и сделать GET на этот адрес, не пытаясь угадать, куда сервер положил ресурс.
### Location в header, а не в JSON
Хочется спросить: «А почему не добавить в body поле url?» Можно и так (иногда так делают), но Location — это именно стандартный «языковой» механизм HTTP для таких ситуаций. Он хорош тем, что не привязан к формату body. Сегодня у вас JSON, завтра (теоретически) другой формат — а заголовок остаётся заголовком и продолжает нести смысл.
Плюс он красиво сочетается со статусом. 201 говорит «создано», Location говорит «вот где». И это ощущается как связанный контракт, а не как случайный набор полей.
### Относительный и абсолютный Location
В учебных примерах часто используют относительный путь:
Location: /api/v1/reading-list/43Это нормально, особенно когда клиент уже знает host и port. В больших системах могут предпочитать абсолютный URI (полностью с https://...), но для нашего уровня сейчас достаточно понимать сам принцип: Location указывает адрес нового ресурса.
### Мини-пример на Java: «собрать Location из id»
public class LocationHeaderDemo {
public static void main(String[] args) {
// Идентификатор только что созданного ресурса (его обычно выдаёт база/сервер)
long id = 43L;
// Location — это адрес, по которому ресурс можно потом получить через GET
String location = "/api/v1/reading-list/" + id;
// Печатаем, чтобы увидеть итоговую строку заголовка
System.out.println(location); // /api/v1/reading-list/43
}
}Звучит банально, но это ровно та логика, которую вы позже будете писать уже в серверной фазе, когда будете формировать реальные ответы. Сейчас мы просто фиксируем: Location — это часть контракта «создание ресурса».
5. Allow и 405 Method Not Allowed
Заголовок Allow обычно появляется, когда сервер отвечает статусом 405 Method Not Allowed. Это довольно тонкая, но очень полезная ситуация: путь существует, сервер понимает, что это за ресурс/маршрут, но выбранный HTTP-метод для него не поддерживается.
Важно: это не то же самое, что 404 Not Found. 404 — это «ресурс/маршрут не найден», а 405 — это «маршрут найден, но вы пришли не тем способом».
Пример из нашего будущего API. Допустим, у коллекции /api/v1/reading-list логично поддерживать GET (прочитать список) и POST (создать элемент). Если клиент по ошибке пошлёт туда DELETE, сервер может ответить:
HTTP/1.1 405 Method Not Allowed
Allow: GET, POSTСмысл Allow очень дружелюбный (и даже слегка пассивно-агрессивный, если читать с интонацией): «Дорогой клиент, вот список методов, которые здесь вообще имеют смысл». Клиенту не нужно гадать, что делать дальше — сервер явно перечисляет допустимые варианты.
### Чем это полезно даже для джуниора
Во-первых, это делает API предсказуемым. Клиент может быстро исправиться. Во-вторых, это отличная ранняя привычка точности: вы не смешиваете «не тот метод» с «не найдено» или с «что-то сломалось». В-третьих, это один из тех моментов, где потом Spring MVC действительно помогает: фреймворк может сам корректно возвращать 405 и Allow, если вы правильно задекларировали обработчики. Но чтобы ценить автоматизацию, полезно один раз понять смысл руками.
### Мини-пример: Allow в коде
import java.util.Set;
import java.util.StringJoiner;
public class AllowHeaderDemo {
public static void main(String[] args) {
// Набор методов, которые реально разрешены на конкретном пути
Set<String> allowedMethods = Set.of("GET", "POST");
// Склеиваем методы в строку формата "GET, POST" — так выглядит значение Allow
StringJoiner joiner = new StringJoiner(", ");
for (String method : allowedMethods) {
// Каждый метод — отдельный элемент списка
joiner.add(method);
}
// Это и будет значение заголовка Allow в ответе сервера
String allowHeaderValue = joiner.toString();
System.out.println(allowHeaderValue); // GET, POST (порядок может отличаться)
}
}Это всего лишь демонстрация идеи: Allow — это перечисление методов. Позже мы будем думать о порядке, стабильности и о том, где эту логику хранить, но сегодня нам важна семантика.
6. Как это выглядит в сценариях ReadLater
Сейчас мы ещё не запускаем свой HTTP-сервер и не пишем HTTP-клиент на Java — это будет сильно позже по курсу. Но уже сегодня полезно «примерить» заголовки на наши будущие сценарии ReadLater Starter, чтобы они перестали быть абстрактными. Мы будем смотреть на них как на часть договорённости: что клиент обещает/ожидает и что сервер подтверждает/сообщает.
Ниже — небольшая табличка-«шпаргалка» именно по заголовкам, без попытки разбирать всё остальное (методы и статусы вы уже видели в лекциях 1–2, а размещение данных по path/query/body — будет в следующей лекции).
| Сценарий | Заголовки запроса (минимум) | Заголовки ответа (минимум) |
|---|---|---|
| Чтение списка | Accept: application/json | Content-Type: application/json |
| Создание элемента | Content-Type: application/json и Accept: application/json | Content-Type: application/json, а при 201 ещё Location: /api/v1/reading-list/{id} |
| Удаление элемента | (обычно достаточно Accept) | при 204 обычно нет Content-Type и нет body |
| Неподдерживаемый метод на существующем пути | (любой) | Allow: ... вместе с 405 |
Если смотреть на эту табличку как на «контрактные привычки», то получаются простые правила. Accept — это «я хочу вот такой формат», Content-Type — «я отправил/вернул вот такой формат», Location — «вот адрес того, что вы только что создали», Allow — «вот что тут вообще можно делать».
И да, это тот самый момент, где многие новички сначала пытаются жить «только body»: отправляют JSON, получают JSON и считают, что этого достаточно. А потом внезапно встречают ситуацию, где сервер говорит «не понимаю» или «не тем методом», и оказывается, что без статуса и headers контракт вообще не читается.
7. Типичные ошибки при работе с заголовками
Ошибки с заголовками обычно коварны тем, что выглядят «несерьёзно»: поменяли одну строку, подумаешь. А на практике именно из-за одной строки вы можете потерять час на отладку и начать подозревать вселенский заговор, Java, Gradle и погоду за окном. Поэтому лучше заранее знать, где чаще всего наступают на грабли.
Ошибка №1: путать Accept и Content-Type.
Самый классический сценарий — вы отправляете POST с JSON, но ставите только Accept: application/json и забываете Content-Type. В результате вы честно сообщили, какой ответ хотите получить, но вообще не сказали серверу, что вы отправили в body. Сервер может попытаться угадать, может отказать, может «прочитать как текст». В любом случае контракт становится неявным, а значит — хрупким.
Ошибка №2: Content-Type обещает одно, а body содержит другое.
Это почти как подписать коробку «чай», положить туда кофе и удивляться, что человек заваривает «что-то странное». Например, Content-Type: application/json, а тело — просто строка title=Clean Code. Даже если сервер «как-то проглотил», вы сами себе усложнили жизнь: дальше будет невозможно стабильно поддерживать клиент и сервер, потому что договорённость нарушена.
Ошибка №3: ставить Content-Type там, где нет body (и ожидать, что это что-то меняет).
Иногда новички ставят Content-Type в GET-запрос «на всякий случай». Это не катастрофа, но это шум. Заголовок описывает тело, которого нет — значит, он вводит в заблуждение и создаёт ощущение, что где-то должно быть тело. Такие мелочи потом превращаются в «контрактную пыль», от которой сложно отмыться.
Ошибка №4: использовать Location как декоративную ленточку “на каждый успех”.
Location — не «дополнительная информация в ответе», а конкретный смысл: адрес ресурса (чаще всего — только что созданного). Если вы возвращаете Location в ответ на GET или на PUT, клиент начинает думать: «Так, а что я сейчас создал? Куда меня зовут?» Иногда Location уместен и в других сценариях, но на нашем уровне лучше держать правило жёстко: POST создал ресурс — значит, 201 и Location.
Ошибка №5: Allow не соответствует реальности.
Если сервер говорит Allow: GET, POST, а на самом деле POST не работает (или наоборот), клиенту становится хуже, чем если бы Allow не было. Заголовок превращается в ложную подсказку. Поэтому Allow — это не «текст для галочки», а часть договора: перечисляйте только то, что реально поддерживается для данного пути.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ