Kurz-Doku: Gruppen‑Kalender‑API (öffentlich)

Diese API stellt die nächsten Termine (Occurrences) als JSON bereit – global oder gefiltert nach einer bestimmten Gruppe. Sie ist öffentlich lesbar (ohne Authentifizierung) und durch Rate Limiting geschützt.

Basis

• Lokaler Standard‑Host: http://127.0.0.1:8000
• Alle Pfade unten sind relativ zu diesem Host.

Endpunkte

• Nächste Termine (global):
  • GET /api/public/events/upcoming
• Nächste Termine einer Gruppe (per Slug):
  • GET /api/public/groups/{group}/events/upcoming
  • {group} ist der Gruppen‑Slug, z. B. teen-treff.

Abfrageparameter (optional)

• limit — Anzahl Einträge (Standard 5, min 1, max 20)
• offset — Anzahl Einträge überspringen (0‑basiert)
• index — Nur den n‑ten Eintrag (1‑basiert). Setzt intern offset = index - 1. Wenn limit fehlt, wird limit = 1 verwendet.

Beispiele

• Nur der nächste Termin einer Gruppe:
  • GET /api/public/groups/teen-treff/events/upcoming?index=1
• Paginieren mit Offset und Limit:
  • GET /api/public/groups/teen-treff/events/upcoming?offset=5&limit=10

Antwortformat (JSON)

Die Antwort ist ein Array von Terminen. Jeder Termin enthält u. a. folgende Felder:

• id (number)
• title (string)
• starts_at (ISO‑8601, z. B. 2025-12-05T18:30:00+01:00)
• ends_at (ISO‑8601 oder null)
• description (string oder null)
• status (string, z. B. scheduled, canceled)
• is_canceled (bool)
• allow_attach (bool)
• group (Objekt mit name, url, short_description oder null)
• site (Objekt mit name, address, url oder null)
• meeting_point (Objekt mit id, name, city, address, coordinates, url oder null)
• location (vereinheitlichtes Ziel mit type, name, address, coordinates, url)
• image_url (string oder null)
• bookable (bool)
• url (Detailseite des Termins im Web)

Minimalbeispiel

[
  {
    "id": 123,
    "title": "Teen‑Treff",
    "starts_at": "2025-12-05T18:30:00+01:00",
    "ends_at": "2025-12-05T20:00:00+01:00",
    "description": null,
    "status": "scheduled",
    "is_canceled": false,
    "allow_attach": false,
    "group": {
      "name": "Teen‑Treff",
      "url": "http://127.0.0.1:8000/groups/teen-treff",
      "short_description": "…"
    },
    "site": null,
    "meeting_point": {
      "id": 7,
      "name": "Gemeindehaus",
      "city": "Dettingen",
      "address": "Hauptstr. 1, 72581 Dettingen",
      "coordinates": [48.5, 9.3],
      "url": "http://127.0.0.1:8000/meeting-points/7"
    },
    "location": {
      "type": "meeting_point",
      "name": "Gemeindehaus",
      "address": "Hauptstr. 1, 72581 Dettingen",
      "coordinates": [48.5, 9.3],
      "url": "http://127.0.0.1:8000/meeting-points/7"
    },
    "image_url": null,
    "bookable": false,
    "url": "http://127.0.0.1:8000/groups/teen-treff/occurrences/123"
  }
]

Beispiele zum Aufruf

cURL (nächste 5 Termine global)

curl -s "http://127.0.0.1:8000/api/public/events/upcoming?limit=5" | jq .

cURL (nur der nächste Termin einer Gruppe)

curl -s "http://127.0.0.1:8000/api/public/groups/krabbelgruppe-dettingen/events/upcoming?index=1" | jq .

JavaScript Fetch (Browser/Node)

const res = await fetch('/api/public/groups/teen-treff/events/upcoming?limit=5');
const data = await res.json();
console.log(data);

Hinweise

• Zeitformat: ISO‑8601 mit Zeitzone.
• Sortierung: chronologisch nach starts_at (danach id). Enthält auch aktuell laufende Termine.
• Rate Limiting: derzeit 60 Requests/Minute (pro IP) via Middleware throttle:60,1.
• Authentifizierung: nicht erforderlich; read‑only.
• Stabilität: Felder können erweitert werden; bestehende Felder bleiben abwärtskompatibel erhalten.

Schnellzugriff über die Gruppenseite

Auf der Gruppenseite /groups/{slug} finden Sie im Abschnitt „Nächste Termine“ rechts neben dem ICS‑Icon ein JSON‑API‑Icon. Ein Klick öffnet die API‑Antwort im neuen Tab.

• Beispielseite: http://127.0.0.1:8000/groups/krabbelgruppe-dettingen
• API‑Link: http://127.0.0.1:8000/api/public/groups/krabbelgruppe-dettingen/events/upcoming