Какие знаешь HTTP-запросы?

HTTP Методы (запросы)

Понимание HTTP методов — критично для BA при проектировании API и интеграций. Вот мой практический разбор.

1. Основные HTTP методы (CRUD operations)

GET — Читать (Read)

• Безопасный (не изменяет данные)
• Идемпотентный (можно вызывать много раз, результат один и тот же)
• Данные в URL (query parameters)
• Кэшируется браузером

GET /api/users?filter=active — получить список активных пользователей
GET /api/users/123 — получить пользователя с id 123
GET /api/users/123/orders — получить заказы пользователя 123

POST — Создавать (Create)

• Не безопасный (изменяет данные)
• Не идемпотентный (каждый вызов создает новый ресурс)
• Данные в body
• Не кэшируется

POST /api/users — создать нового пользователя
  Body: {name: "John", email: "john@example.com"}
  Response: {id: 123, name: "John", created_at: "2025-03-26T10:00:00Z"}

POST /api/users/123/orders — создать заказ для пользователя 123
  Body: {items: [...]}
  Response: {id: 456, user_id: 123, status: "pending"}

PUT — Обновить полностью (Update)

• Не безопасный (изменяет данные)
• Идемпотентный (результат один и тот же несмотря на количество вызовов)
• Обновляет ВСЕ поля ресурса
• Данные в body

PUT /api/users/123 — обновить пользователя 123
  Body: {name: "Jane", email: "jane@example.com", phone: "+1234567890"}
  Результат: все поля обновлены (если какое-то поле не передано, оно обнулится)

PATCH — Обновить частично (Partial Update)

• Не безопасный
• Идемпотентный
• Обновляет ТОЛЬКО переданные поля
• Данные в body

PATCH /api/users/123 — обновить только name
  Body: {name: "Jane"}
  Результат: обновляется только name, остальные поля не трогаются

Разница PUT vs PATCH:

Исходный ресурс:
{
  "id": 123,
  "name": "John",
  "email": "john@example.com",
  "phone": "+1111111111"
}

Посланный body: {"name": "Jane"}

PUT результат:
{
  "id": 123,
  "name": "Jane",
  "email": null,  ← стёрлось!
  "phone": null   ← стёрлось!
}

PATCH результат:
{
  "id": 123,
  "name": "Jane",
  "email": "john@example.com",  ← не изменилось
  "phone": "+1111111111"         ← не изменилось
}

DELETE — Удалить (Delete)

• Не безопасный (удаляет данные)
• Идемпотентный (второй вызов вернет 404, но результат один — ресурса нет)
• Данные в URL или body

DELETE /api/users/123 — удалить пользователя 123
  Response: 204 No Content (или 200 с сообщением)

DELETE /api/users/123/orders/456 — удалить заказ

2. Другие HTTP методы

HEAD — как GET, но без body в ответе

• Проверить существует ли ресурс
• Узнать метаданные (размер файла, дату изменения)

HEAD /api/users/123 — проверить существует ли пользователь
Response: 200 OK (но без body)

OPTIONS — узнать какие методы поддерживает endpoint

• Используется браузером перед CORS запросом
• Для человека редко нужно

OPTIONS /api/users — узнать какие методы поддерживает
Response:
Allow: GET, POST, PUT, DELETE, OPTIONS

3. Safe vs Idempotent

Safe методы (безопасные):

• Не изменяют данные на сервере
• GET, HEAD, OPTIONS
• Можно вызывать много раз без побочных эффектов

Idempotent методы (идемпотентные):

• Результат один и тот же независимо от количества вызовов
• GET, HEAD, PUT, DELETE, OPTIONS
• POST — НЕ идемпотентный (каждый вызов создает новый ресурс)
• PATCH — может быть не идемпотентный (зависит от реализации)

Примеры:

GET /api/users/123 — результат всегда одинаковый (safe + idempotent)
POST /api/users — создает новый ресурс каждый раз (не safe, не idempotent)
DELETE /api/users/123 — второй вызов вернет 404, но тот же результат (не safe, идемпotent)
PUT /api/users/123 — обновляет на одни и те же значения (не safe, идемпотент)

Почему это важно для BA:

Если мы проектируем API и хотим retry logic:

• GET можно переделать безопасно (вызвать много раз)
• POST нужен Idempotency-Key (иначе дублирование)
• DELETE безопасен для retry

4. HTTP Status Codes (коды ответов)

2xx Success (успех)

200 OK — обычный успешный ответ (GET, POST, PUT, PATCH, DELETE)
201 Created — ресурс успешно создан (POST)
202 Accepted — запрос принят, обработка асинхронно (POST для длительных операций)
204 No Content — успех, но нет body (DELETE, PATCH без ответа)

3xx Redirection (перенаправление)

301 Moved Permanently — ресурс перемещён навсегда (браузер обновляет ссылку)
302 Found — временное перенаправление
304 Not Modified — ресурс не изменился с момента кэша (браузер использует кэш)

4xx Client Error (ошибка клиента)

400 Bad Request — неправильный формат запроса (неправильный JSON)
401 Unauthorized — нет аутентификации (нужен token)
403 Forbidden — аутентифицирован, но нет прав (не разрешено удалять других пользователей)
404 Not Found — ресурс не существует
409 Conflict — конфликт (попытка обновить стареющие данные)
422 Unprocessable Entity — валидация данных не прошла (email не валидный)
429 Too Many Requests — слишком много запросов (rate limiting)

5xx Server Error (ошибка сервера)

500 Internal Server Error — ошибка на сервере (баг в коде)
502 Bad Gateway — сервер не доступен
503 Service Unavailable — сервер перегружен
504 Gateway Timeout — запрос занял слишком долго

5. Практические примеры

Пример 1: REST API для управления пользователями

GET /api/v1/users
  → Status: 200
  → Response: [{id: 1, name: "John"}, {id: 2, name: "Jane"}]

GET /api/v1/users/1
  → Status: 200
  → Response: {id: 1, name: "John", email: "john@example.com"}

GET /api/v1/users/999
  → Status: 404
  → Response: {error: "User not found"}

POST /api/v1/users
  → Body: {name: "Bob", email: "bob@example.com"}
  → Status: 201
  → Response: {id: 3, name: "Bob", email: "bob@example.com", created_at: "..."}

PUT /api/v1/users/1
  → Body: {name: "John Doe", email: "john.doe@example.com"}
  → Status: 200
  → Response: {id: 1, name: "John Doe", email: "john.doe@example.com"}

PATCH /api/v1/users/1
  → Body: {email: "newemail@example.com"}
  → Status: 200
  → Response: {id: 1, name: "John Doe", email: "newemail@example.com"}

DELETE /api/v1/users/1
  → Status: 204 No Content

Пример 2: Интеграция с платёжной системой

Получить доступные методы оплаты:
GET /api/v3/payment-methods
  → Status: 200
  → Response: [{id: "card", name: "Card"}, {id: "wallet", name: "Wallet"}]

Создать платёж:
POST /api/v3/payments
  → Body: {amount: 10000, currency: "RUB", payment_method: "card"}
  → Status: 201
  → Response: {id: "pay_123", status: "pending", confirmation_url: "..."}

Получить статус платежа:
GET /api/v3/payments/pay_123
  → Status: 200
  → Response: {id: "pay_123", status: "succeeded", amount: 10000}

Отменить платёж:
DELETE /api/v3/payments/pay_123
  → Status: 200
  → Response: {id: "pay_123", status: "cancelled"}

Пример 3: Rate Limiting и Retry

Запрашиваю слишком быстро:
GET /api/users (запрос #1000 за 1 минуту)
  → Status: 429 Too Many Requests
  → Response: {error: "Rate limit exceeded", retry_after: 60}
  → Headers: X-RateLimit-Limit: 100, X-RateLimit-Remaining: 0

Это значит: прекратить запросы, попробовать через 60 секунд.

6. Headers (заголовки HTTP)

Важные headers для BA:

Authorization: Bearer token_here
  → Аутентификация (передаём токен)

Content-Type: application/json
  → Говорим серверу что данные в JSON

Accept: application/json
  → Просим вернуть ответ в JSON

X-Request-ID: unique-id-123
  → Для трейсинга запроса (корреляция логов)

Idempotency-Key: unique-key-456
  → Для идемпотентности (не дублировать при retry)

X-Custom-Header: value
  → Кастомные headers (если нужны)

Cache-Control: max-age=3600
  → Кэширование (кэшировать на 3600 секунд)

Content-Length: 256
  → Размер body

User-Agent: MyApp/1.0
  → Информация о клиенте

7. Когда использовать какой метод

GET — когда...

• Нужно получить данные
• Читаем, не меняем
• Примеры: список заказов, профиль пользователя, поиск

POST — когда...

• Создаём новый ресурс
• Запускаем действие (отправить письмо, начать процесс)
• Примеры: создать заказ, залогиниться, загрузить файл

PUT — когда...

• Обновляем весь ресурс полностью
• Редко используется в реальных API
• Примеры: обновить профиль целиком

PATCH — когда...

• Обновляем ресурс частично
• Чаще всего это PATCH, не PUT
• Примеры: изменить только email, только status

DELETE — когда...

• Удаляем ресурс
• Примеры: удалить заказ, удалить аккаунт

8. Ошибки которые часто делают

Ошибка 1: GET для создания

❌ GET /api/users/create?name=John
✅ POST /api/users с body {name: "John"}

Ошибка 2: POST для обновления (без Idempotency-Key)

❌ POST /api/payments без Idempotency-Key (дублируется при retry)
✅ POST /api/payments с Idempotency-Key (retry безопасен)

Ошибка 3: PUT когда нужен PATCH

❌ PUT /api/users/123 {name: "Jane"} → остальные поля обнулятся
✅ PATCH /api/users/123 {name: "Jane"} → остальные поля не трогаются

Ошибка 4: Не использовать правильный статус код

❌ POST /api/users → Status: 200 (неправильно)
✅ POST /api/users → Status: 201 (правильно)

❌ DELETE /api/users/999 → Status: 500 (если не найден)
✅ DELETE /api/users/999 → Status: 404 (правильно)

9. REST API Design Best Practices

Правило 1: Используй существительные, не глаголы

❌ GET /api/getUsers
❌ POST /api/createUser
❌ PUT /api/updateUser/123
✅ GET /api/users
✅ POST /api/users
✅ PUT /api/users/123

Правило 2: Версионирование

✅ /api/v1/users
✅ /api/v2/users (если изменился формат)

Правило 3: Вложенные ресурсы

✅ GET /api/users/123/orders (заказы пользователя 123)
✅ GET /api/users/123/orders/456 (заказ 456 пользователя 123)

Правило 4: Фильтрация, сортировка, пагинация

✅ GET /api/users?filter=active&sort=name&limit=10&offset=0

Чек-лист для BA при проектировании API

• ✅ Определены все endpoints
• ✅ Для каждого endpoint указан метод (GET, POST, etc)
• ✅ Определены параметры (обязательные, опциональные)
• ✅ Определены возможные status codes
• ✅ Определены примеры запроса и ответа
• ✅ Задокументированы все ошибки
• ✅ Определено rate limiting
• ✅ Определена аутентификация и авторизация
• ✅ Определено версионирование
• ✅ Определены retry strategy (Idempotency-Key если нужно)

Итог

Понимание HTTP методов и кодов — базовый навык для BA. Это позволяет:

• Правильно проектировать API
• Общаться с разработчиками на одном языке
• Документировать интеграции
• Предвидеть проблемы