🧩 Проектирование REST API
REST API — самый частый способ, которым бэкенд отдаёт данные фронтенду, мобильному приложению и партнёрам. Методы и коды ответов разобраны на странице «HTTP: методы, коды и версии». Здесь про то, как из них собрать API, которым удобно пользоваться и который переживёт пять релизов: адреса ресурсов, формат ошибок, пагинация, повтор POST без дублей и версии. На собеседовании мидлу часто дают задачу «спроектируй API для заказов», и по ответу сразу видно, писал ли человек контракты сам
🧠 Как это устроено
REST описал Рой Филдинг в диссертации 2000 года как набор ограничений для распределённых систем. Сервер не хранит состояние клиента между запросами, ответы можно кэшировать, а у всех ресурсов единый интерфейс: адрес плюс стандартные методы. На практике «REST API» означает проще: данные разложены по ресурсам с понятными адресами, а действие выражено методом HTTP, а не словом в URL
Ресурсы и адреса
Ресурс — существительное, с которым работает клиент: заказ, пользователь, платёж. Коллекция называется во множественном числе, конкретный объект — коллекция плюс id:
| Действие | Плохо | Хорошо |
|---|---|---|
| Список заказов | GET /getOrders | GET /orders |
| Один заказ | GET /order?id=42 | GET /orders/42 |
| Создать | POST /createOrder | POST /orders |
| Изменить статус | POST /orders/42/update | PATCH /orders/42 |
| Позиции заказа | GET /orderItems?orderId=42 | GET /orders/42/items |
| Фильтр | GET /orders/status/paid | GET /orders?status=paid |
Вложенность больше одного уровня (/users/7/orders/42/items/3) быстро становится неудобной: чтобы получить позицию, клиенту нужно знать всю цепочку. Если у позиции есть свой глобальный id, хватит /order-items/3
Не всё ложится на CRUD. За «отменить заказ» стоит больше, чем смена поля: деньги возвращаются, склад снимает резерв. Есть два честных варианта. Первый — POST /orders/42/cancel, действие как подресурс. Второй — PATCH /orders/42 с {"status": "cancelled"}, если отмена и правда сводится к переходу статуса. Первый понятнее, когда у действия свои параметры и свои ошибки. Google в своих правилах API называет такие действия custom methods и пишет их через двоеточие: POST /orders/42:cancel. Выбери один стиль и держи его во всём API
Ошибки в одном формате
Код ответа говорит клиенту, что делать дальше, а тело объясняет, что именно не так. Если каждая ручка придумывает свой формат ошибки, клиенту приходится писать разбор под каждую. Стандартный формат описан в RFC 9457 Problem Details, он заменил RFC 7807. Ответ идёт с Content-Type: application/problem+json:
{
"type": "https://api.example.com/problems/insufficient-funds",
"title": "Недостаточно средств",
"status": 422,
"detail": "На счёте 300 ₽, а заказ стоит 1200 ₽",
"instance": "/orders/42"
}type — стабильный идентификатор вида ошибки, по нему клиент ветвит логику. title один на тип, detail описывает этот конкретный случай. Можно добавлять свои поля, например список невалидных полей формы. status дублирует код ответа для удобства, но HTTP-код обязан быть таким же
Пагинация: offset или курсор
Список без лимита работает, пока данных мало: сегодня в таблице 200 заказов, через год 2 миллиона, и одна ручка кладёт базу. Поэтому у любой коллекции есть лимит по умолчанию и максимальный размер страницы
Offset-пагинация — GET /orders?limit=20&offset=40. Просто сделать, можно прыгнуть на страницу 7. Но у неё две проблемы. Первая — скорость: Postgres всё равно вычисляет все пропущенные строки, и OFFSET 1000000 читает миллион строк, чтобы выбросить их. Вторая — дрейф: если между запросами страниц кто-то добавил заказ в начало, последний элемент первой страницы окажется первым на второй, и клиент увидит его дважды
Курсорная пагинация (её ещё называют keyset) запоминает, на чём остановились, и продолжает с этого места:
-- первая страница
SELECT id, created_at, total FROM orders
ORDER BY created_at DESC, id DESC
LIMIT 21;
-- следующая: всё, что строго после последней строки прошлой страницы
SELECT id, created_at, total FROM orders
WHERE (created_at, id) < ($1, $2)
ORDER BY created_at DESC, id DESC
LIMIT 21;С индексом по (created_at, id) база сразу находит место продолжения, и сотая страница стоит столько же, сколько первая. id в сортировке нужен, чтобы порядок был однозначным: у двух заказов может совпасть время. Запрашивают 21 строку, а отдают 20: если пришла двадцать первая, следующая страница есть
Клиенту курсор отдают непрозрачной строкой, обычно base64 от created_at и id. Так сервер может поменять его устройство, и ни один клиент не сломается. В правилах API Google (AIP-158) это поля page_size, page_token и next_page_token, и пустой next_page_token значит, что дальше страниц нет
| Offset | Курсор | |
|---|---|---|
| Скорость на глубоких страницах | Падает линейно | Постоянная |
| Перейти на страницу N | Можно | Нельзя |
| Дубли и пропуски при вставках | Бывают | Нет |
| Общее число страниц | Легко посчитать, но COUNT(*) дорогой | Обычно не отдают |
Offset нормален для админки с таблицей на тысячи строк, где людям нужны номера страниц. Ленты, история операций, выгрузки и всё, что листают далеко, — курсором
Повтор POST без дублей
POST не идемпотентен: клиент отправил «создай заказ», получил таймаут и не знает, создался ли заказ. Повторит — может получить два. Решение — ключ идемпотентности. Клиент генерирует уникальный ключ на операцию, обычно UUID, и шлёт его в заголовке Idempotency-Key. При повторе ключ тот же
Сервер на первый запрос с ключом выполняет операцию и сохраняет код и тело ответа. На повтор с тем же ключом он не выполняет ничего и отдаёт сохранённый ответ. Так устроен API Stripe: ключи живут минимум 24 часа, а повтор с тем же ключом, но другими параметрами возвращает ошибку. Заголовок сейчас стандартизуют в IETF (черновик draft-ietf-httpapi-idempotency-key-header), и там предложены коды:
- 400 — ручка требует ключ, а его нет
- 422 — ключ уже использован с другим телом запроса
- 409 — первый запрос с этим ключом ещё выполняется
Самое тонкое место — два одинаковых запроса, пришедшие одновременно. Если сервер сначала проверяет «есть ли ключ», а сохраняет его после операции, оба запроса пройдут проверку. Правильно — сначала вставить ключ со статусом «выполняется» в таблицу с уникальным индексом. Второй запрос упадёт на уникальности и получит 409, а не создаст дубль
Частичное обновление и параллельные правки
PUT заменяет ресурс целиком, поэтому клиент обязан прислать все поля, иначе забытые обнулятся. Для изменения пары полей берут PATCH. Самый простой формат тела — JSON Merge Patch (RFC 7396): присланные поля заменяются, неприсланные остаются, null удаляет поле. У него есть граница: им нельзя записать в поле именно null. Если null в модели — осмысленное значение, нужен JSON Patch (RFC 6902) со списком операций или своя схема
Когда два менеджера одновременно открыли заказ и оба сохранили правки, второй молча затрёт первого. Это потерянное обновление, и HTTP решает его условными запросами. Сервер отдаёт заказ с ETag: "7", где 7 — версия записи. Клиент сохраняет правку с If-Match: "7". Если за это время версия стала 8, сервер отвечает 412 Precondition Failed, и клиент перечитывает заказ. Требовать такой заголовок можно кодом 428 Precondition Required. В базе это одна строка: UPDATE ... SET ..., version = version + 1 WHERE id = $1 AND version = $2, и ноль обновлённых строк означает конфликт
Версии и обратная совместимость
Версию чаще всего пишут в путь: /v1/orders. Её видно в логах, её легко развести на балансировщике. Альтернатива — заголовок или media type, это чище по REST, но неудобно отлаживать через браузер и curl. Ни один способ не спасёт, если ломать контракт без нужды
Совместимые изменения не требуют новой версии: новое необязательное поле в ответе, новый необязательный параметр, новая ручка. Ломающие требуют: удалить или переименовать поле, сменить его тип, сделать параметр обязательным, поменять смысл кода ответа. Чтобы новое поле ничего не сломало, клиенты не должны падать на незнакомых полях. Новую мажорную версию заводят редко, а старую держат, пока по ней ходит трафик, и смотрят этот трафик в метриках
Долгие операции
Если операция идёт минуты (отчёт, импорт, видео), держать HTTP-запрос открытым нельзя: оборвётся на таймауте прокси. Сервер отвечает 202 Accepted с адресом операции в Location, клиент опрашивает GET /operations/123 или получает вебхук, когда статус станет done или failed
🛠️ На практике
Контракт пишут до кода, обычно в OpenAPI: его читают фронтенд и QA, по нему генерируют клиентов и проверяют запросы. Актуальная версия спецификации — 3.2. Вот как выглядит обмен для ленты заказов с курсором:
GET /v1/orders?status=paid&page_size=2
200 OK
{
"items": [
{"id": "ord_9", "status": "paid", "total": 1200, "createdAt": "2026-11-09T10:15:00Z"},
{"id": "ord_8", "status": "paid", "total": 450, "createdAt": "2026-11-09T09:02:00Z"}
],
"nextPageToken": "eyJjIjoiMjAyNi0xMS0wOVQwOTowMjowMFoiLCJpIjoib3JkXzgifQ"
}С Go 1.22 стандартный http.ServeMux понимает метод и параметры в шаблоне, и для REST-роутинга внешний роутер больше не обязателен:
mux := http.NewServeMux()
mux.HandleFunc("GET /v1/orders", listOrders)
mux.HandleFunc("POST /v1/orders", createOrder)
mux.HandleFunc("GET /v1/orders/{id}", getOrder) // id достаётся через r.PathValue("id")
mux.HandleFunc("POST /v1/orders/{id}/cancel", cancelOrder)Если путь совпал, а метод нет, мукс сам ответит 405 и перечислит разрешённые методы в заголовке Allow
Ниже минимальный обработчик с ключом идемпотентности. Ключи лежат в памяти под мьютексом, чтобы пример был коротким. В настоящем сервисе это таблица с уникальным индексом по ключу и сроком жизни, а ключ вставляется до выполнения операции:
Go · POST с Idempotency-Key и ошибками в формате RFC 9457
type saved struct {
bodyHash [32]byte
status int
resp string
}
var (
mu sync.Mutex
keys = map[string]saved{} // в проде — таблица в Postgres или Redis с TTL
nextID = 100
)
func createOrder(w http.ResponseWriter, r *http.Request) {
key := r.Header.Get("Idempotency-Key")
body, _ := io.ReadAll(r.Body)
hash := sha256.Sum256(body)
if key == "" {
problem(w, 400, "Idempotency-Key is missing")
return
}
mu.Lock()
defer mu.Unlock()
if s, ok := keys[key]; ok {
if s.bodyHash != hash {
problem(w, 422, "Idempotency-Key is already used")
return
}
w.WriteHeader(s.status) // повтор: отдаём сохранённый ответ, заказ не создаём
io.WriteString(w, s.resp)
return
}
nextID++
resp := fmt.Sprintf(`{"id":%d}`, nextID)
keys[key] = saved{hash, http.StatusCreated, resp}
w.Header().Set("Location", fmt.Sprintf("/orders/%d", nextID))
w.WriteHeader(http.StatusCreated)
io.WriteString(w, resp)
}
func problem(w http.ResponseWriter, status int, title string) {
w.Header().Set("Content-Type", "application/problem+json")
w.WriteHeader(status)
fmt.Fprintf(w, `{"title":%q,"status":%d}`, title, status)
}Четыре запроса: создание, повтор после таймаута, тот же ключ с другим телом и запрос без ключа:
201 {"id":101}
201 {"id":101}
422 {"title":"Idempotency-Key is already used","status":422}
400 {"title":"Idempotency-Key is missing","status":400}Повтор вернул тот же заказ 101, второй не создался. Это и есть вся идея: клиент может повторять сколько угодно, эффект один
⚠️ Где ошибаются
- Глаголы в адресах.
/getOrders,/createOrder,/deleteUser?id=7. Метод уже говорит, что делать, а глагол в пути ломает кэширование и привычные инструменты: прокси не знает, чтоGET /deleteUserопасен - Всё через один POST.
POST /apiс{"action": "getOrder"}и всегда 200. Это RPC в обёртке HTTP: мониторинг не видит ошибок, кэш не работает, а клиент разбирает каждое тело. Если нужен RPC, честнее взять gRPC - Наружу отдают модель из базы. Ответ — это сериализованная структура ORM, и переименование колонки ломает мобильное приложение, которое обновится через месяц. Ответ API — отдельная структура, контракт меняется осознанно
- Offset на большой ленте. Всё быстро на тесте с сотней строк, а на проде запрос сотой страницы идёт секунды. Если ленту будут листать глубоко, сразу закладывай курсор: поменять тип пагинации потом — ломающее изменение
- Ключ идемпотентности сохраняют после операции. Два одновременных повтора оба не находят ключ и оба создают заказ. Ключ вставляют первым шагом, уникальность проверяет база
- Новая версия на каждое изменение.
/v7/ordersчерез год значит, что команда не отличает совместимые изменения от ломающих и поддерживает семь копий одного API
🎯 Вопросы с собеседований
Что такое REST и что делает API RESTful?
REST — архитектурный стиль, который описал Рой Филдинг: клиент и сервер разделены, сервер не хранит состояние клиента между запросами, ответы можно кэшировать, у ресурсов единый интерфейс. На практике RESTful API — это ресурсы с понятными адресами, действия через методы HTTP, честные коды ответов и stateless-запросы, где каждый несёт всё нужное, включая токен. Строгий REST требует ещё ссылок между ресурсами в ответах (HATEOAS), но в большинстве API их нет, и это стоит знать
Как сделать пагинацию? Чем offset хуже курсора?
Offset-пагинация пропускает N строк: просто и можно перейти на любую страницу, но база вычисляет все пропущенные строки, поэтому глубокие страницы медленные. Ещё при вставках между запросами элементы съезжают, и клиент видит дубли или пропуски. Курсорная пагинация продолжает с последнего ключа сортировки через WHERE (created_at, id) < (...) и индекс, поэтому любая страница стоит одинаково и ничего не съезжает. Минус курсора — нельзя прыгнуть на страницу N. Курсор отдают клиенту непрозрачной строкой
Как сделать создание заказа идемпотентным?
Клиент генерирует ключ идемпотентности на операцию, например UUID, и шлёт его в заголовке Idempotency-Key, при повторе тот же. Сервер первым делом вставляет ключ в таблицу с уникальным индексом, выполняет операцию и сохраняет ответ. На повтор он отдаёт сохранённый ответ. Тот же ключ с другим телом получает ошибку 422, а повтор во время выполнения первого запроса — 409. Ключи хранят ограниченное время, у Stripe это минимум 24 часа
Как версионировать API и что считается ломающим изменением?
Обычно версию пишут в путь, /v1/..., реже в заголовок. Добавить необязательное поле, параметр или ручку можно без новой версии, если клиенты игнорируют незнакомые поля. Удалить или переименовать поле, сменить тип, сделать параметр обязательным или поменять смысл ответа — ломающие изменения, им нужна новая версия. Старую версию держат, пока по метрикам по ней есть трафик, и заранее предупреждают клиентов
Как возвращать ошибки из API?
Правильным HTTP-кодом, чтобы ретраи, мониторинг и кэши работали без разбора тела, и в едином формате тела. Стандарт для этого — RFC 9457 Problem Details: type как стабильный идентификатор ошибки, title, status, detail про конкретный случай и свои поля, например список невалидных полей. Внутренние детали вроде стектрейса или текста ошибки базы наружу не отдают
Два пользователя одновременно правят один заказ. Как не потерять изменения?
Через оптимистическую блокировку. У записи есть версия, сервер отдаёт её в ETag, клиент сохраняет правку с If-Match. В базе обновление идёт с условием WHERE id = $1 AND version = $2, и если строка не обновилась, сервер отвечает 412 Precondition Failed. Клиент перечитывает заказ и показывает пользователю конфликт. Пессимистическая блокировка на время редактирования в вебе не подходит: пользователь может закрыть вкладку и держать блокировку вечно
Что делать, если операция занимает несколько минут?
Не держать HTTP-запрос открытым: его оборвёт таймаут балансировщика или клиента. Сервер принимает задачу, ставит её в очередь и отвечает 202 Accepted с адресом операции. Клиент опрашивает статус по этому адресу или получает вебхук, когда операция завершится. Сама операция при этом должна быть идемпотентной, потому что воркер может взять задачу повторно
📚 Что почитать
- RFC 9457: Problem Details for HTTP APIs — короткий стандарт формата ошибок с примерами расширений
- We need tool support for keyset pagination — Маркус Винанд показывает, почему offset медленный и как устроен keyset на разных базах
- AIP-158: Pagination — правила пагинации в API Google: размер страницы, токены, поведение на краях
- Idempotent requests в API Stripe — как ключи идемпотентности работают в большом платёжном API
- Routing Enhancements for Go 1.22 — шаблоны с методами и параметрами в
http.ServeMux