Siirry pääsisällölle

Päätepisteiden viite

Tämä osio kuvaa kaikki ChurchApps API:n tarjoamat REST-päätepisteet. Jokainen moduulisivu luettelee kaikki reitit HTTP-metodeineen, polkuineen, todennusvaatimuksineen ja vaadittuine oikeuksineen.

Perus-URL​

YmpäristöURL
Paikallinen kehityshttp://localhost:8084
Tuotantohttps://api.churchapps.org

Pyyntöjen käytännöt​

  • Content-Type: Kaikki pyyntö- ja vastausrungot käyttävät muotoa application/json
  • Monivuokraus: Jokainen todennettu pyyntö rajataan JWT-tokenista poimittuun churchId-arvoon. churchId-arvoa ei välitetä URL-osoitteessa
  • Erätallennus: Useimmat POST-päätepisteet hyväksyvät olioiden taulukon. API lisää uudet tietueet (ilman id-kenttää) ja päivittää olemassa olevat (joissa on id-kenttä) yhdellä kutsulla
  • Tunnisteet: Kaikki kohdetunnisteet ovat UUID-muotoisia

Esimerkki: Erätallennus​

POST /membership/people
Authorization: Bearer <token>

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

Ensimmäinen olio luodaan (uusi); toinen päivitetään (siinä on id).

Vastausmuoto​

Onnistuneet vastaukset palauttavat JSON-muotoista dataa, joko yksittäisen olion tai taulukon. Virhevastaukset käyttävät HTTP-standardin tilakoodeja:

KoodiMerkitys
200Onnistui
400Virheellinen pyyntö (validointivirheet)
401Ei valtuuksia (token puuttuu tai on virheellinen, tai oikeudet eivät riitä)
404Ei löytynyt
500Palvelinvirhe

Validointivirheet palauttavat:

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

Päätepistetaulukoiden lukeminen​

Jokaisella moduulisivulla päätepisteet on järjestetty ohjaimen mukaan. Taulukoissa on seuraavat sarakkeet:

SarakeKuvaus
MetodiHTTP-metodi (GET, POST, DELETE)
PolkuReitti suhteessa ohjaimen perusreittiin
TodennusJWT = vaatii Bearer-tokenin, Public = ei todennusta
OikeusVaadittu oikeus (esim. People.Edit). — tarkoittaa, että mikä tahansa todennettu käyttäjä voi käyttää päätepistettä
KuvausMitä päätepiste tekee

Ohjaimet, jotka perivät vakiomuotoisen CRUD-kantaluokan, tarjoavat automaattisesti neljä päätepistettä: GET / (listaa kaikki), GET /:id (hae tunnisteen perusteella), POST / (luo tai päivitä) ja DELETE /:id (poista).

Raportointimoduuli​

Raportointimoduuli toimii eri tavalla kuin muut moduulit. Tietokantapohjaisen CRUD-toiminnon sijaan se lataa raporttimääritykset levyllä olevista JSON-tiedostoista ja suorittaa parametroituja SQL-kyselyitä.

MetodiPolkuTodennusKuvaus
GET/reporting/reports/:keyNameJWTLataa raporttimääritys avaimen nimen perusteella
GET/reporting/reports/:keyName/runJWTSuorita raportti ja palauta tulokset

Raportin parametrit välitetään kyselymerkkijonon arvoina (esim. ?startDate=2024-01-01&endDate=2024-12-31). churchId-parametri lisätään automaattisesti JWT-tokenista. Jokainen raporttimääritys voi määrittää omat oikeusvaatimuksensa.

Moduulihakemisto​

ModuuliPerusreittiKuvaus
Authentication/membership/users, /membership/oauthKirjautuminen, rekisteröityminen, JWT-tokenit, OAuth, oikeudet
Membership/membership/*Henkilöt, seurakunnat, ryhmät, taloudet, roolit, lomakkeet, asetukset
Attendance/attendance/*Kampukset, palvelut, istunnot, vierailut, sisäänkirjautumistiedot
Content/content/*Sivut, saarnat, tapahtumat, tiedostot, galleriat, Raamattu, suoratoisto
Giving/giving/*Lahjoitukset, rahastot, maksuyhdyskäytävät, tilaukset
Messaging/messaging/*Keskustelut, ilmoitukset, laitteet, tekstiviestit
Doing/doing/*Suunnitelmat, tehtävät, tehtävänjaot, automaatiot, aikataulutus