Kirken ACTS Vejle API og dokumentation

Adgang og autentifikation

De dokumenterede læsefunktioner er offentlige. Du behøver hverken login, API-nøgle eller cookies. Brug HTTPS og GET. HEAD henter kun headers, og OPTIONS viser de tilladte metoder.

API og OpenAPI

GET /api og /api/v1 returnerer JSON-oversigter med links til de offentlige ressourcer. /api/v1 indeholder også den maskinlæsbare versions- og ratepolitik. OpenAPI 3.0.4-specifikationen indeholder unikke operationId-værdier, beskrivelser, typede parametre og JSON-svarskemaer til function calling.

curl -H "Accept: application/json" https://actsvejle.dk/api

Versioner og udfasning

Den stabile JSON-API bruger hovedversion i URL'en: /api/v1. API-Version: 1 bekræfter versionen i svaret. Breaking changes får en ny URL, fx /api/v2; tilføjelser kan ske i v1, så klienter skal ignorere ukendte svarfelter. Ingen version eller kalenderabonnementer er planlagt udfaset. Før en version lukkes, offentliggør vi mindst 90 dages varsel her og sender Deprecation som en RFC 9745-dato (@<unix-sekunder>), Sunset som en RFC 8594 HTTP-dato og Link med rel=deprecation på de berørte svar. Et varsel ændrer ikke funktionaliteten før den annoncerede dato.

Kalender som JSON

GET /api/v1/events returnerer offentlige, konkrete forekomster med id, oversat titel og beskrivelse, dato, klokkeslæt, sted og kategorier. Gentagelser, aflysninger og datooverstyringer følger hjemmesidens kalender. Tider er lokale i Europe/Copenhagen. lang er da, en, de eller es (standard da); manglende oversættelser bruger engelsk og derefter dansk. from og to er inklusive startdatoer i YYYY-MM-DD, fra 1970 til 9998; standarden er dags dato i København til 90 dage senere. Intervallet må højst være 366 dage. limit er 1–100 (standard 50), offset er et ikke-negativt sikkert heltal (standard 0); fortsæt med pagination.nextOffset indtil null. Kalenderen kan ændre sig mellem sider. category og type bruger samme filtre som abonnementet nedenfor. Andre parametre, gentagne enkeltparametre og ugyldige sprog giver 400. På /api/calendar kan JSON også vælges med Accept: application/json; uden dette bevares iCalendar, også ved */* og ens præference.

curl -i -H "Accept: application/json" "https://actsvejle.dk/api/v1/events?lang=en&limit=10"

Kalender

GET /api/calendar returnerer den eksisterende iCalendar-feed som text/calendar i UTF-8. Brug en RFC 5545-parser, der håndterer gentagelser, undtagelser og tidszonen Europe/Copenhagen. Kalenderen viser aktuelle offentlige begivenheder; en tom kalender er ikke det samme som en driftsfejl.

lang er da, en, de eller es; standarden og fallback for ukendte sprog er da. Gentag category=<id> eller type=<værdi> for at kombinere valg. Find kategori-id'er i den offentlige kalenders abonnementslinks. Højst 64 kategori- og typeværdier tilsammen. type kan være service, kids, groups, worship eller special og gælder kun begivenheder uden kategori. Udelad begge filtre for alle begivenheder. Ukendte, gyldige kategori-id'er giver et tomt udvalg. Andre query-parametre ignoreres.

curl -H "Accept: text/calendar" "https://actsvejle.dk/api/calendar?lang=en"

Hjemmesiden som Markdown

Læs offentlige sider med Accept: text/markdown, eller tilføj .md til adressen. Forsiden findes på /index.md. Dansk bruger ingen sprogpræfiks; engelsk, tysk og spansk bruger /en, /de og /es. Kalenderens Markdown-side er en introduktion; brug kalenderens feed til aktuelle datoer. Ukendte Markdown-sider beholder deres Markdown-svar med HTTP 404.

curl -H "Accept: text/markdown" https://actsvejle.dk/en/om-os

Fejl og løsning

Kalenderfejl, ukendte API-adresser og afviste skrivemetoder på de dokumenterede API'er returnerer RFC 9457 JSON med Content-Type: application/problem+json. Felterne er type, title, status, detail, instance, code og hint. code er en stabil fejlkode; hint beskriver næste skridt. Brug HTTP-status og code i din kode.

400 INVALID_CALENDAR_SELECTION: Ret tomme eller ugyldige filtre, eller reducer antallet til højst 64 værdier.

400 INVALID_EVENT_QUERY: Ret JSON-kalenderens sprog, datointerval, pagination eller filtre efter /openapi.json.

404 API_NOT_FOUND: Find en eksisterende API-adresse via /api eller /openapi.json.

405 METHOD_NOT_ALLOWED: Brug GET, HEAD eller OPTIONS. Allow-headeren angiver de tilladte metoder.

429 RATE_LIMITED: Vent det antal sekunder, Retry-After angiver. RateLimit viser resterende kvote (r) og sekunder til nulstilling (t).

503 CALENDAR_UNAVAILABLE: Vent 300 sekunder, som angivet i Retry-After, før du prøver igen. Fejlsvar må ikke caches.

curl -i "https://actsvejle.dk/api/calendar?type=invalid"

Cache og brug

JSON-ruterne /api, /api/v1 og /api/v1/events samt JSON-svar fra /api/calendar har en burstgrænse på 120 forespørgsler pr. 60 sekunder pr. klient-IP, rute og serverinstans. GET, HEAD, OPTIONS og afviste metoder tæller med på JSON-ruterne. RateLimit-Policy: "instance-read";q=120;w=60 og RateLimit: "instance-read";r=<resterende>;t=<sekunder> følger IETF-udkast draft-ietf-httpapi-ratelimit-headers-11, som endnu ikke er en RFC. Ved 429 sendes Retry-After; denne har forrang. JSON-svar og kvoteoplysninger må ikke caches. Tællerne nulstilles ved genstart og deles ikke mellem serverinstanser; det er ikke en global kvote. Ved mange samtidige klienter kan nye klienter dele en konservativ fælles kvote på instansen. Hostingplatformen kan begrænse trafik yderligere. Genbrug hentede data mellem spørgsmål. iCalendar-abonnementer bevarer deres cache på 300 sekunder og er uden for JSON-burstgrænsen. Autentifikation og interne administrative API'er følger deres eksisterende protokoller.

Handlinger og kontakt

API'et giver læseadgang til offentlig information. Tilmelding, beskeder og donationer kræver brugerens beslutning og en faktisk bekræftelse fra tjenesten. Der findes intet offentligt agent-API til betalinger, bookinger, personfølsomme oplysninger eller administration.