REST API на собеседовании системного аналитика

Что спрашивают

REST на собесе системного аналитика — базовый минимум. Без свободного владения HTTP-методами, статусами и принципами REST дальше технического раунда обычно не идут.

Глубже спрашивают:

• Как спроектировать API под бизнес-задачу
• Идемпотентность и какие методы идемпотентны по спецификации
• Версионирование, обратная совместимость
• Async-сценарии: webhooks, long polling, SSE
• Обработка ошибок и resilience: retries, circuit breaker

HTTP: методы, статусы, идемпотентность

Методы

• GET — получить ресурс. Идемпотентен, безопасен (не изменяет состояние)
• POST — создать ресурс. Не идемпотентен (повтор создаёт дубликаты)
• PUT — заменить ресурс целиком. Идемпотентен
• PATCH — частичное обновление. По спецификации НЕ идемпотентен, на практике обычно делают идемпотентным
• DELETE — удалить. Идемпотентен (повторное удаление — 404 или 204)
• HEAD — как GET, но без тела
• OPTIONS — для CORS

Статусы

• 2xx — успех. 200 OK, 201 Created (с location), 202 Accepted (async), 204 No Content
• 3xx — редиректы. 301 Moved Permanently, 302 Found, 304 Not Modified
• 4xx — ошибка клиента. 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
• 5xx — ошибка сервера. 500 Internal Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout

На собесе типичный вопрос: «Чем отличается 401 от 403?» Ответ: 401 — не аутентифицирован (нет токена или токен невалиден). 403 — аутентифицирован, но нет прав.

Идемпотентность на практике

POST не идемпотентен по спецификации, но в реальной работе нужно сделать idempotent. Подход — клиент передаёт Idempotency-Key:

POST /payments
Idempotency-Key: 5d4f8a1b-3a2c-4f6e-9d2b-1c4f5e6a7b8c

{ "amount": 1000, "currency": "RUB" }

Сервер хранит ключ N часов и при повторе возвращает прежний результат. Это стандарт для платёжных API (Stripe, ЮKassa).

Дизайн REST-эндпоинтов

Хороший REST использует существительные (ресурсы), не глаголы:

• /users — коллекция
• /users/{id} — конкретный ресурс
• /users/{id}/orders — вложенные ресурсы

Плохой:

• /getUserById — это RPC, не REST
• /createUser — это RPC

Действия выражаются через метод, не URL.

Исключения — там где действие не вписывается в CRUD:

• POST /users/{id}/activate — допустимо
• POST /payments/{id}/refund — допустимо

Версионирование

Три подхода:

• URL — /v1/users, /v2/users. Самый явный, прост в кэшировании. В РФ — самый частый
• Header — Accept: application/vnd.api.v2+json. Чище, но сложнее в дебаге
• Query param — /users?version=2. Худший вариант, ломает кеширование

На собесе спросят: «Какие версии будете поддерживать одновременно?» Ответ: обычно 2 — текущую и предыдущую. Старые клиенты должны успеть мигрировать.

Пагинация и фильтрация

Offset-based

/orders?limit=50&offset=100 — простая, но плохо работает на больших объёмах. Каждая страница — full scan до offset.

Cursor-based

/orders?limit=50&after=abc123 — масштабируется лучше. Нужен стабильный sort key.

Keyset

/orders?limit=50&created_after=2026-05-01T12:00:00Z — частный случай cursor.

На собесе спросят: «Что выберешь для бесконечного скролла в фиде?» Ответ: cursor-based, потому что offset на 100К+ записях деградирует, а у пользователя на фиде позиция стабильная.

Фильтрация

• /orders?status=completed&min_amount=1000 — простые фильтры через query params
• Сложные фильтры — POST на специальный search endpoint с body

Resilience и обработка ошибок

Retry

Клиент повторяет запрос при сетевой ошибке или 5xx. Используется только для идемпотентных запросов (или с Idempotency-Key для POST).

Backoff: exponential + jitter (не повторять с одинаковыми интервалами, иначе DDoS-эффект на сервер при восстановлении).

Circuit Breaker

Если сервис стабильно падает, перестаём бить в него на N секунд. Защита от каскадных падений.

Timeout

Каждый клиент должен иметь таймаут. Без таймаута поток зависает на минуты.

Rate limiting

Сервер возвращает 429 Too Many Requests с заголовком Retry-After. Клиент ждёт указанное время.

OpenAPI / Swagger

OpenAPI — стандарт описания REST API в YAML/JSON. Swagger — UI для просмотра OpenAPI-документации.

Что включает:

• Эндпоинты, методы, параметры
• Схемы request/response
• Коды ошибок
• Примеры
• Аутентификация

На собесе спросят написать кусок OpenAPI для эндпоинта. Приготовьте простой пример наизусть.

Частые ошибки

Использовать GET для изменений. GET должен быть безопасен. Если запрос меняет состояние — это не GET.

Возвращать 200 на ошибки. Структура {"success": false, "error": "..."} с 200 OK — не REST. Используйте 4xx/5xx.

Не считать идемпотентность. В платежах, регистрациях, заказах повторный запрос может произойти из-за сетевых проблем. Без идемпотентности — дубликаты.

Фильтрация в URL до бесконечности. /orders?status=a&category=b&min_amount=c&max_amount=d&country=e&... — ломает кеширование. Сложные фильтры — POST.

Раскрывать internal IDs. UUID лучше, чем sequential int. Не выдавать структуру БД через API.

FAQ

REST vs GraphQL — что лучше?

Зависит от задачи. REST проще, кешируется. GraphQL гибче для клиента (один запрос — много данных). На собесе СА чаще REST.

Сколько REST-эндпоинтов написать перед собесом?

Спроектируйте 3 полных API: для платежей, для каталога товаров, для регистрации. Этого хватит, чтобы уверенно говорить.

Это официальная информация?

Нет. Статья основана на спецификациях (RFC 7231, RFC 9110) и опыте кандидатов.