Prejsť na hlavný obsah

Referencia koncových bodov

Táto sekcia dokumentuje všetky REST koncové body, ktoré sprístupňuje ChurchApps API. Každá stránka modulu uvádza všetky trasy s ich HTTP metódou, cestou, požiadavkami na autentifikáciu a potrebnými oprávneniami.

Základná URL​

ProstredieURL
Lokálny vývojhttp://localhost:8084
Produkciahttps://api.churchapps.org

Konvencie požiadaviek​

  • Content-Type: Všetky telá požiadaviek a odpovedí používajú application/json
  • Viacnájomcovosť (multi-tenant): Každá autentifikovaná požiadavka je viazaná na churchId extrahované z JWT tokenu — churchId do URL neposielate
  • Hromadné ukladanie: Väčšina POST koncových bodov prijíma pole objektov. API v jedinom volaní vloží nové záznamy (bez poľa id) a aktualizuje existujúce (s poľom id)
  • ID: Všetky ID entít sú UUID

Príklad: hromadné uloženie​

POST /membership/people
Authorization: Bearer <token>

[
{ "firstName": "Jane", "lastName": "Doe" },
{ "id": "abc-123", "firstName": "John", "lastName": "Smith" }
]

Prvý objekt sa vytvorí (je nový); druhý sa aktualizuje (má id).

Formát odpovede​

Úspešné odpovede vracajú JSON — buď jeden objekt, alebo pole. Chybové odpovede používajú štandardné HTTP stavové kódy:

KódVýznam
200Úspech
400Chybná požiadavka (chyby validácie)
401Neautorizované (chýbajúci alebo neplatný token, alebo nedostatočné oprávnenia)
404Nenájdené
500Chyba servera

Chyby validácie vracajú:

{
"errors": [
{ "msg": "enter a valid email address", "param": "email", "location": "body" }
]
}

Ako čítať tabuľky koncových bodov​

Každá stránka modulu organizuje koncové body podľa kontroléra. Tabuľky používajú tieto stĺpce:

StĺpecPopis
MetódaHTTP metóda (GET, POST, DELETE)
CestaCesta trasy relatívna k základnej ceste kontroléra
AutentifikáciaJWT = vyžaduje Bearer token, Public = nevyžaduje autentifikáciu
OprávneniePožadované oprávnenie (napr. People.Edit). — znamená ľubovoľného autentifikovaného používateľa
PopisČo koncový bod robí

Kontroléry, ktoré dedia zo štandardnej základnej triedy CRUD, poskytujú automaticky štyri koncové body: GET / (zoznam všetkých záznamov), GET /:id (získanie podľa ID), POST / (vytvorenie alebo aktualizácia) a DELETE /:id (vymazanie).

Modul Reporting​

Modul Reporting funguje inak ako ostatné moduly. Namiesto operácií CRUD nad databázou načítava definície reportov z JSON súborov na disku a vykonáva parametrizované SQL dotazy.

MetódaCestaAutentifikáciaPopis
GET/reporting/reports/:keyNameJWTNačíta definíciu reportu podľa kľúča
GET/reporting/reports/:keyName/runJWTSpustí report a vráti výsledky

Parametre reportu sa odovzdávajú ako hodnoty v reťazci dotazu (napr. ?startDate=2024-01-01&endDate=2024-12-31). Parameter churchId sa automaticky vkladá z JWT tokenu. Každá definícia reportu môže určiť vlastné požiadavky na oprávnenia.

Index modulov​

ModulZákladná cestaPopis
Autentifikácia/membership/users, /membership/oauthPrihlásenie, registrácia, JWT tokeny, OAuth, oprávnenia
Členstvo/membership/*Ľudia, cirkvi, skupiny, domácnosti, roly, formuláre, nastavenia
Účasť/attendance/*Kampusy, služby, relácie, návštevy, záznamy o prihlásení
Obsah/content/*Stránky, kázne, udalosti, súbory, galérie, Biblia, streamovanie
Dary/giving/*Dary, fondy, platobné brány, predplatné
Správy/messaging/*Konverzácie, oznámenia, zariadenia, SMS
Doing/doing/*Plány, úlohy, priradenia, automatizácie, plánovanie