Этот документ не фиксирует API готового продукта. Он задаёт правила оформления и ожидания для будущих сервисов, которые будут добавлены в репозиторий
| Принцип | Смысл |
|---|---|
| Контракт прежде реализации | Сначала описывается формат, потом код |
| Нейтральность | Документ не привязан к конкретному домену |
| Единообразие | Все API-документы следуют одной структуре |
| Ясность | По документу можно понять, что и где искать |
Для каждого будущего приложения рекомендуется хранить собственный API-раздел внутри docs/ или рядом с соответствующим модулем
- базовый префикс маршрутов;
- форматы входных и выходных данных;
- правила авторизации, если они есть;
- соглашение об ошибках;
- особенности пагинации и сортировки;
- ссылку на актуальную спецификацию, если она генерируется автоматически
Пока репозиторий пустой, разделы ниже используются как ориентир для будущих сервисов.
| Группа | Назначение |
|---|---|
health |
Проверка доступности сервиса |
auth |
Аутентификация и управление сессией |
profile |
Пользовательские данные и настройки |
admin |
Управляющие операции для администраторов |
system |
Служебные и диагностические маршруты |
| Параметр | Рекомендация |
|---|---|
| Формат тел | JSON |
| Кодировка | UTF-8 |
| Имена полей | Понятные и стабильные |
| Временные значения | ISO 8601 |
| Версионирование | Через префикс маршрута или отдельную спецификацию |
{
"success": true,
"data": {},
"meta": {}
}| Ситуация | Подход |
|---|---|
| Успешный запрос | Возвращается корректный JSON-ответ |
| Ошибка валидации | Возвращается понятное сообщение с деталями |
| Ошибка доступа | Возвращается код, отражающий отсутствие прав |
| Системная ошибка | Возвращается нейтральное сообщение без утечки лишних деталей |
Если в проекте появится полноценная OpenAPI-спецификация, именно она становится источником истины для API