Pereiti prie pagrindiniam turinį

Galutinių taškų nuoroda

Šiame skyriuje aprašyti visi REST galutiniai taškai, kuriuos teikia ChurchApps API. Kiekviename modulio puslapyje išvardyti visi maršrutai su HTTP metodu, keliu, autentifikavimo reikalavimais ir reikalingais leidimais.

Bazinis URL​

AplinkaURL
Vietinė kūrimo aplinkahttp://localhost:8084
Produkcinė aplinkahttps://api.churchapps.org

Užklausų konvencijos​

  • Content-Type: Visi užklausų ir atsakymų turiniai naudoja application/json
  • Multi-tenant: Kiekviena autentifikuota užklausa apribojama churchId, išgautu iš JWT žetono – churchId URL adrese perduoti nereikia
  • Masinis išsaugojimas: Dauguma POST galutinių taškų priima objektų masyvą. API vienu kvietimu įterps naujus įrašus (be id lauko) ir atnaujins esamus įrašus (su id lauku)
  • ID: Visi subjektų ID yra UUID

Pavyzdys: masinis išsaugojimas​

POST /membership/people
Authorization: Bearer <token>

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

Pirmasis objektas bus sukurtas (naujas), o antrasis – atnaujintas (turi id).

Atsakymo formatas​

Sėkmingi atsakymai grąžina JSON – arba vieną objektą, arba masyvą. Klaidų atsakymai naudoja standartinius HTTP statuso kodus:

KodasReikšmė
200Sėkmingai
400Neteisinga užklausa (validacijos klaidos)
401Neautorizuota (trūksta arba netinkamas žetonas, arba nepakanka leidimų)
404Nerasta
500Serverio klaida

Validacijos klaidos grąžina:

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

Kaip skaityti galutinių taškų lenteles​

Kiekvienas modulio puslapis galutinius taškus suskirsto pagal valdiklį (controller). Lentelėse naudojami šie stulpeliai:

StulpelisAprašymas
MetodasHTTP metodas (GET, POST, DELETE)
KeliasMaršruto kelias, santykinis valdiklio bazinio kelio atžvilgiu
AuthJWT = reikalingas Bearer žetonas, Public = autentifikavimas nereikalingas
LeidimasReikalingas leidimas (pvz., People.Edit). — reiškia, kad pakanka bet kurio prisijungusio naudotojo
AprašymasKą daro galutinis taškas

Valdikliai, paveldintys standartinę CRUD bazinę klasę, automatiškai pateikia keturis galutinius taškus: GET / (išvardyti visus), GET /:id (gauti pagal ID), POST / (sukurti arba atnaujinti) ir DELETE /:id (ištrinti).

Ataskaitų modulis​

Ataskaitų modulis veikia kitaip nei kiti moduliai. Vietoj duomenų bazėje saugomų CRUD operacijų jis įkelia ataskaitų aprašus iš JSON failų diske ir vykdo parametrizuotas SQL užklausas.

MetodasKeliasAuthAprašymas
GET/reporting/reports/:keyNameJWTĮkelti ataskaitos aprašą pagal raktinį pavadinimą
GET/reporting/reports/:keyName/runJWTVykdyti ataskaitą ir grąžinti rezultatus

Ataskaitų parametrai perduodami kaip užklausos eilutės reikšmės (pvz., ?startDate=2024-01-01&endDate=2024-12-31). Parametras churchId automatiškai įtraukiamas iš JWT žetono. Kiekvienas ataskaitos aprašas gali nurodyti savo leidimų reikalavimus.

Modulių rodyklė​

ModulisBazinis keliasAprašymas
Autentifikavimas/membership/users, /membership/oauthPrisijungimas, registracija, JWT žetonai, OAuth, leidimai
Narystė/membership/*Asmenys, bažnyčios, grupės, namų ūkiai, vaidmenys, formos, nustatymai
Lankomumas/attendance/*Filialai, pamaldos, sesijos, apsilankymai, registracijos įrašai
Turinys/content/*Puslapiai, pamokslai, renginiai, failai, galerijos, Biblija, transliacijos
Aukojimai/giving/*Aukos, fondai, mokėjimų vartai, prenumeratos
Pranešimai/messaging/*Pokalbiai, pranešimai, įrenginiai, SMS
Doing/doing/*Planai, užduotys, priskyrimai, automatizavimas, tvarkaraščiai