Справочник по эндпоинтам
В этом разделе документированы все REST-эндпоинты, предоставляемые API ChurchApps. На странице каждого модуля перечислены все маршруты с HTTP-методом, путём, требованиями аутентификации и необходимыми разрешениями.
Базовый URL
| Окружение | URL |
|---|---|
| Локальная разработка | http://localhost:8084 |
| Продакшен | https://api.churchapps.org |
Соглашения по запросам
- Content-Type: Все тела запросов и ответов используют
application/json - Мультитенантность: Каждый аутентифицированный запрос ограничен
churchId, извлечённым из JWT-токена -- вам не нужно передаватьchurchIdв URL - Пакетное сохранение: Большинство
POST-эндпоинтов принимают массив объектов. API вставит новые записи (без поляid) и обновит существующие (с полемid) за один вызов - Идентификаторы: Все ID сущностей являются UUID
Пример: Пакетное сохранение
POST /membership/people
Authorization: Bearer <token>
[
{ "firstName": "Jane", "lastName": "Doe" },
{ "id": "abc-123", "firstName": "John", "lastName": "Smith" }
]
Первый объект создаётся (новый); второй обновляется (имеет id).
Формат ответа
Успешные ответы возвращают JSON -- один объект или массив. Ответы с ошибками используют стандартные HTTP-коды состояния:
| Код | Значение |
|---|---|
200 | Успех |
400 | Некорректный запрос (ошибки валидации) |
401 | Не авторизован (отсутствующий/недействительный токен или недостаточные разрешения) |
404 | Не найдено |
500 | Ошибка сервера |
Ошибки валидации возвращают:
{
"errors": [
{ "msg": "enter a valid email address", "param": "email", "location": "body" }
]
}
Как читать таблицы эндпоинтов
На странице каждого модуля эндпоинты организованы по контроллерам. В таблицах используются следующие столбцы:
| Столбец | Описание |
|---|---|
| Метод | HTTP-метод (GET, POST, DELETE) |
| Путь | Путь маршрута относительно базового пути контроллера |
| Аутентификация | JWT = требуется Bearer-токен, Public = аутентификация не требуется |
| Разрешение | Необходимое разрешение (напр. People.Edit). — означает любого аутентифицированного пользователя |
| Описание | Что делает эндпоинт |
Контроллеры, наследующие стандартный CRUD-базовый класс, автоматически предоставляют четыре эндпоинта: GET / (список всех), GET /:id (получить по ID), POST / (создать/обновить) и DELETE /:id (удалить).
Модуль отчётности
Модуль отчётности работает иначе, чем другие модули. Вместо CRUD на основе базы данных он загружает определения отчётов из JSON-файлов на диске и выполняет параметризованные SQL-запросы.
| Метод | Путь | Аутентификация | Описание |
|---|---|---|---|
| GET | /reporting/reports/:keyName | JWT | Загрузить определение отчёта по имени ключа |
| GET | /reporting/reports/:keyName/run | JWT | Выполнить отчёт и вернуть результаты |
Параметры отчёта передаются как значения строки запроса (напр. ?startDate=2024-01-01&endDate=2024-12-31). Параметр churchId автоматически подставляется из JWT-токена. Каждое определение отчёта может указывать собственные требования к разрешениям.
Указатель модулей
| Модуль | Базовый путь | Описание |
|---|---|---|
| Аутентификация | /membership/users, /membership/oauth | Вход, регистрация, JWT-токены, OAuth, разрешения |
| Membership | /membership/* | Люди, церкви, группы, домохозяйства, роли, формы, настройки |
| Attendance | /attendance/* | Кампусы, служения, сессии, посещения, записи регистрации |
| Content | /content/* | Страницы, проповеди, события, файлы, галереи, Библия, трансляции |
| Giving | /giving/* | Пожертвования, фонды, платёжные шлюзы, подписки |
| Messaging | /messaging/* | Переписки, уведомления, устройства, SMS |
| Doing | /doing/* | Планы, задачи, назначения, автоматизации, расписание |