💡 Headers в API: что это и зачем 💡

Headers – заголовки запроса и ответа в протоколе HTTP.

Это дополнительные системные параметры, которыми надо обмениваться. Обычно сквозные для всех методов в API, то есть применяются сразу для всех методов.

Помогают:
✔️ Определять, как обрабатывать запрос.
✔️ Передавать метаинформацию о данных (системную).
✔️ Настраивать взаимодействие между клиентом и сервером.


Проще всего разобраться с Headers, познакомившись с набором стандартных значений, которые можно нагло копировать в требования к вашим REST API методам 🙂


📌 Request Headers - для запросов

◽️ Authorization
Используется для передачи токенов доступа, ключей API или других данных для авторизации. Используется для проверки доступа к API-методам.
🔗 Подробнее в подкасте

Authorization: Bearer <token>

◽️ Content-Type
Сообщает серверу, в каком формате отправлены данные.
Если сервер не знает в каком формате переданы данные, то он не сможет обработать запрос.
Если его нет в API, то сервер обычно ждёт JSON, если в документации не указано иное.

Content-Type: application/json

Content-Type: application/xml

◽️ Cache-Control
Управляет кэшированием данных на клиенте.
Полезно для работы с экономией трафика.

Cache-Control: no-cache

◽️ Ключи идемпотентности - название придумываете сами
Это уникальный идентификатор для запросов, который помогает избежать дублирования. Например, при повторной отправке платежного запроса сервер проверяет ключ и не создаёт дубль.
Подробнее в подкасте

Idempotency-Key: <unique-key>

◽️ Часовые пояса
Когда система работает в разных регионах, важно учитывать часовые пояса и их можно передавать как обязательные заголовки во всех запросах.
Стандартные названия из моего опыта:

Time-Zone: UTC+3

X-Time-Zone: UTC+3

📌 + помним про Response Headers (заголовки ответов)


Полные подборки стандартных Headers:
🔗 Wikipedia
🔗 MDN


Правильно выбранные Headers помогают удобно передавать все системные параметры для обмена данными, которые не важны для бизнес-логики и алгоритмов работы API-методов.

#RestApiGA

🧑‍💻 Какой HTTP-код вернуть? Шпаргалка для проектирования API-методов 🧑‍💻

В любой интеграции по API важно не только предусмотреть happy path (успешный путь), но и заранее описать, как система должна вести себя при ошибках.


📌 Что нужно сделать при проектировании ответов на API-запросы

0️⃣ Перечислить успешные ответы
+ 200 OK - Успех
+ 201 Created — Создано (новая запись в БД)
+ 202 Accepted — Принято в обработку (запрос принят, но обработка не завершена, часто используется при асинхронных задачах - отчёты, отправка email и др)
+ 204 No Content — Нет содержимого (запрос выполнен успешно, но в ответе нет тела)


1️⃣ Перечислить типовые ошибки и описать реакцию API на них:
+ 401 Unauthorized — Неверный логин/токен
+ 403 Forbidden — Нет прав
+ 429 Too Many Requests — Превышен лимит запросов


2️⃣ Добавить требования к специфичным ошибкам:
+ 400 Bad Request — Ошибка во входных данных
+ 409 Conflict — Создание дубликатов
+ 500 Internal Server Error — Внутренний сбой в работе сервера
+ и другие.
Все HTTP-статусы тут.


3️⃣ Добавить альтернативные сценарии в Use Case для API-метода, которые ведут к описанным в п.1 и 2 ошибкам.

2А. Клиент передал номер телефона в неверном формате.
→ Вернуть ошибку HTTP-400 и сообщение "Неверный формат номера телефона, ожидается 10 цифр"

4️⃣ Сделать JSON-структуру ответов об ошибках единообразной

{
"errorCode": "INVALID_PHONE",
"message": "Текст ошибки"
}

5️⃣ В OpenAPI спецификации (Swagger) добавить секции:

responses:
'400':
description: Неверные параметры запроса
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'

6️⃣ Отразить примеры ошибок в документации Confluence и всегда иметь соответствующий раздел в шаблоне задачи.



Помните, что ошибки тоже важная часть программного интерфейса - API!

Если все ошибки задокументированны чётко и понятно, пользователи (и разработчики) будут вам благодарны, и вы сможете повысить UX приложений 🙌


🔗 Cтатья про документирование ошибок в REST API


#RestApiGA

✨ Завершаем предзапись на REST API | с 5 августа ✨

Актуально добавить знания и опыт по REST API в резюме и портфолио? Тогда рекомендую посмотреть нашу практическую программу:

💻 Дизайн REST API
🗓 Старт 5 августа 2025

☀️ До ноября (когда будет основной онлайн-поток) учитесь самостоятельно, в комфортном темпе + получаете доп. практику, которая будет доступна только для вашей группы

Поток с новым форматом:
⚡️ +3 месяца доступа к материалам и обратной связи (9 мес)
⚡️ +3 онлайн-встречи, где все с доступом к микрофону и практикуются
⚡️ +1 проект

Результат - 2 проекта в портфолио:
✅ Постановки задач и документация в Confluence
✅ Postman-коллекции и интерактивная API-документация
✅ Swagger-документация
✅ Работающие на загрушках ваши API-методы (mock api)

🔗 Узнать подробности и записаться


🗓 До 25 июля
Запись на самых выгодных условиях с дополнительным обучением по БД в подарок.


Есть вопросы? Пишите @getanalyst или заполняйте анкету предзаписи на сайте. Мы свяжемся с вами, поможем оценить текущие навыки и ответим на вопросы! 🤝

🗓❤️‍🔥 [Открытый урок] От практики REST API в Postman до внедрения личного AI-ассистента ❤️‍🔥🗓

REST API — стандарт в большинстве IT-проектов. Поэтому глубокое понимание его работы и принципов проектирования уже давно спрашивают с аналитиков.

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


Чтобы разобраться в них на практике, приглашаем на открытый урок:

🐞 Как избежать ошибок в REST API:
🤖 от практики в Postman до помощи AI-ассистента
🗓 Доступ 2 - 5 августа [сб-вт]

👉 Подробности и регистрация

План:
1. Теория по REST API на практике в Postman
2. 5 ошибок проектирования REST API
3. Шаблон постановки задачи на API
4. AI-инструменты для работы


Этот открытый урок даст вам и теоретические знания, и практические инструменты 🛠

Будем погружаться в сложную теорию через реальную работу и разбор конкретных примеров.

Занятие проводится как вводный урок к практической программе Дизайн REST API.


Регистрируйтесь, чтобы не пропустить! 😉

🔎 Что входит в хорошую постановку задачи на REST API-метод? 🔎

✅ 1. Общее описание
+ что делает этот метод?
+ для кого он?
+ почему мы его делаем?

✅ 2. Алгоритм работы - Use Case
+ основной сценарий
+ обработка ошибок


Требования к реализации:

✅ 3. Тип метода и полный URL

✅ 4. Query-параметры и их логика

✅ 5. Headers и их логика

✅ 6. Body (json) - Тело запроса

✅ 7. Аутентификация и авторизация запросов

✅ 8. Описание успешного ответа:
+ HTTP-статус код
+ Headers
+ Body (json) - тело ответа

✅ 9. Список обрабатываемых ошибок:
+ HTTP-статус код
+ Headers
+ Body (json) - тело ответа
Не описали ошибку? Значит её обработка не поддерживается.

Перечисленные выше требования (3-9) часто описывают с примерами запросов и ответов. Это самый лучший способ.



✅ 10. Маппинг данных для параметров API с БД
В маппинг включают: path-параметры, query-параметы, json-ы запроа и ответа, headers (если требуется).



✅ + 11. НФТ
Например, ограничения на кол-во запросов с одного ip или от одного клиента.

✅ + 12. Логирование и мониторинг
+ что логировать и где
+ при каких условиях, либо всегда
+ как долго хранить логи
+ требования к дашбордам мониторинга

✅ + 13. Дополнительно
+ Ответственная команда
+ Известные ошибки и проблемы
+ Требования к монетизации
+ Требования к кэшированию
+ Cookies - можно, но не нужно, они не рекомендуются для REST API



📌 Используйте пост как чеклист.
Проверьте, что у вас на работе учитываются все необходимые разделы в постановке задачи.

🧐 Что делают разработчики по тем пунктам, где требования сейчас не описываются, как принимают решения?

Этот чек-лист поможет задать правильные вопросы и избежать «дырок» в описании требований.

А если хочется дополнительных пояснений по наполнению, то можно почитать нашу статью Структура постановки задачи на REST API метод.


Сохраняйте, чтобы не потерять ✨

#RestApiGA

💻 Пример постановки задачи на REST API метод - выгрузка из Confluence 💻

Теория - хорошо, а практика ещё лучше.

Для нашего проекта MeetsGA подготовила пример постановки задачи на метод:

POST /events - создать мероприятие

Изучайте и используйте для работы.

Описание шаблона можно найти тут, и в предыдущем посте 😌

#RestApiGA #MeetsGA

🔥 [Только 2-5 августа] REST API: от практики в Postman до помощи AI-ассистента 🔥

Нужно получить опыт работы с REST API?
+ Научиться проектировать сложные API-методы с нуля и учитывать все нюансы?
+ Избегать типичных ошибок в дизайне?
+ За секунды генерировать спецификации и шаблоны с помощью AI-ассистента?


Вам сюда 👇

🐞 Как избежать ошибок в REST API:
🤖 от практики в Postman до помощи AI-ассистента
🗓 Доступ 2 - 5 августа [сб-вт]

🕘 Время на обучение: 4 часа

👉 Подробности и регистрация


В результате этого бесплатного обучения:
✅ Получите опыт работы с Postman.
✅ Сделаете рабочую Postman-коллекцию для личного портфолио.
✅ Будете знать типичные ошибки при дизайне REST API и как их избежать.
✅ Получите примеры корректных постановок задач на API-методы.
✅ Научитесь использовать ChatGPT на продвинутом уровне для ускорения работы.


Регистрируйтесь и планируйте время на обучение заранее 🤝