«REST API» без осознанной конвенции — это на практике набор эндпоинтов, где каждый называется и пагинируется по-своему. Фронтенду приходится помнить исключения для каждого ресурса.
Что мы фиксируем заранее#
| Аспект | Конвенция |
|---|---|
| Именование ресурсов | множественное число, kebab-case в URL |
| Пагинация | единый формат meta.page/meta.total на всех списках |
| Ошибки валидации | errors.{field} — как отдаёт Laravel Form Request |
| Даты | ISO 8601 в UTC, без исключений |
types/content-api.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 избавляет фронтенд от адаптеров.
