# Дизайн API: чем REST-как-получится хуже осознанной конвенции

Большинство «REST API» в реальных проектах — это набор эндпоинтов без единой конвенции. Показываем, как мы стандартизируем контракт.

*Рубрика: Разработка · Опубликовано: 18 ноября 2025 г. · Автор: Александр Покидов*

Канонический URL: https://pokidov.dev/blog/api-dizain-rest-vs-json-api

---

«REST API» без осознанной конвенции — это на практике набор эндпоинтов, где каждый называется и пагинируется по-своему. Фронтенду приходится помнить исключения для каждого ресурса.

## Что мы фиксируем заранее

| Аспект | Конвенция |
| --- | --- |
| Именование ресурсов | множественное число, kebab-case в URL |
| Пагинация | единый формат meta.page/meta.total на всех списках |
| Ошибки валидации | errors.{field} — как отдаёт Laravel Form Request |
| Даты | ISO 8601 в UTC, без исключений |

types/content-api.ts
```ts
export interface PostResource {
  slug: string;
  category: { slug: string; title: string };
  author: { name: string; position: string; same_as: string[] };
  published_at: string; // ISO 8601
}
```

> **Зачем типизировать ответ API на фронтенде**
TypeScript-интерфейс, синхронизированный с Resource-классом бэкенда, ловит несовпадение полей на этапе компиляции, а не в проде.

## Ключевые выводы

- Единая конвенция именования и пагинации экономит часы на онбординге фронтенд-разработчика.
- Ресурсные классы (Laravel API Resources) — естественная точка контроля версии ответа.
- Явные коды ошибок с машинно-читаемым полем важнее «человеческого» текста сообщения.
- Один и тот же формат ответа для фикстур и боевого API избавляет фронтенд от адаптеров.