REST API
Ресурсы и методы, правильные статусы, единообразные ошибки, пагинация offset или cursor.
Обновлено
Что такое REST API
API — интерфейс, через который одна программа запрашивает данные у другой. REST — самый распространённый стиль веб-API: данные — это ресурсы (пользователи, посты, заказы), у каждого свой URL, а действие задаёт HTTP-метод.
Как фронтендер вы пользуетесь API каждый день. Понимание соглашений помогает их читать, правильно использовать и писать Route Handlers, которые выглядят профессионально.
Соглашения — ресурс + метод
| Метод | URL | Действие | Статус при успехе |
|---|---|---|---|
GET |
/posts |
список | 200 |
GET |
/posts/42 |
один элемент | 200 (404, если нет) |
POST |
/posts |
создаёт | 201 + созданный элемент |
PATCH |
/posts/42 |
частично изменяет | 200 |
PUT |
/posts/42 |
полностью заменяет | 200 |
DELETE |
/posts/42 |
удаляет | 204 без тела |
Правила именования:
- существительные во множественном числе, а не глаголы:
/posts, а не/getPostsили/createPost; - связи через вложенность:
/posts/42/comments; - фильтры, сортировка, пагинация — в query string:
/posts?author=7&sort=-createdAt&page=2.
Ответы и ошибки
// 200 — список с пагинацией
{ "data": [{ "id": 1, "title": "Привет" }], "page": 2, "totalPages": 9 }
// 422 — валидация не прошла
{ "error": "validation", "fieldErrors": { "email": ["Неверный email"] } }| Ситуация | Статус |
|---|---|
| неверные данные | 400 / 422 |
| не аутентифицирован | 401 |
| аутентифицирован, но нет прав | 403 |
| не существует | 404 |
| конфликт (email уже занят) | 409 |
| слишком много запросов | 429 |
| внутренняя ошибка | 500 — без внутренних подробностей в ответе |
Единообразный формат ошибок во всём API сильно упрощает фронтенд.
Пагинация — виды и когда
| Вид | Как | Плюсы | Минусы |
|---|---|---|---|
| offset | ?page=3&perPage=20 → OFFSET 40 LIMIT 20 |
просто, сразу перейти на 7-ю страницу | медленно на больших таблицах; дубли / пропуски, если между запросами добавились данные |
| cursor | ?after=<id-последнего>&limit=20 |
быстро, устойчиво к новым данным | нельзя перейти на «7-ю страницу» |
Нумерованные страницы (админка, поиск) → offset. Бесконечная лента (соцсети, уведомления) → cursor.
REST и альтернативы
| REST | GraphQL | tRPC / Server Actions | |
|---|---|---|---|
| Форма | много URL, HTTP-методы | один эндпоинт, клиент запрашивает ровно нужные поля | вызываете серверные функции прямо из TS |
| HTTP-кэш | естественно | сложно | — |
| Типы клиент-сервер | через OpenAPI / вручную | из схемы | автоматически |
| Когда | публичный API, разные потребители | много клиентов с разными нуждами | фронтенд + бэкенд в одном TS-проекте |
Коротко
- Ресурсы во множественном числе + HTTP-метод определяет действие; правильные статусы (201, 204, 404, 422).
- Фильтры и пагинация в query string; единообразный формат ошибок.
- Offset — для нумерованных страниц, cursor — для бесконечных лент.