EntwicklerAPI-Ressourcen

Veranstalter:innen

Eine Veranstalter:in ist ein Verein, ein Unternehmen oder eine Abteilung der Kommune, die Angebote durchführt. Zu ihrem Veranstalter-Profil gehören Kontaktdaten, eine öffentliche Beschreibung und Mitglieder-Konten. In der API ist ein Veranstalter-Profil ein host.

Endpunkte

GET/hostsAlle Veranstalter:innen abrufen
GET/hosts/{uuid}Eine Veranstalter:in abrufen
POST/hostsEine Veranstalter:in anlegen
PATCH/hosts/{uuid}Eine Veranstalter:in ändern
DELETE/hosts/{uuid}Eine Veranstalter:in löschen
POST/hosts/{uuid}/add-memberEin Mitglied hinzufügen
POST/hosts/{uuid}/remove-memberEin Mitglied entfernen

Das Modell der Veranstalter:in

Name
uuid
Typ
string
Beschreibung
Die Kennung der Veranstalter:in.
Name
name
Typ
string
Beschreibung
Der Name der Veranstalter:in.
Name
alias
Typ
string
Beschreibung
Ein URL-tauglicher Name. Er gilt überall, wo eine Veranstalter:in genannt wird, zum Beispiel in ?host=stadtjugendring-elmsbrueck.
Name
email
Typ
string
Beschreibung
Die öffentliche E-Mail-Adresse.
Name
phone
Typ
string
Beschreibung
Die Telefonnummer.
Name
mobile
Typ
string
Beschreibung
Die Mobilnummer.
Name
fax
Typ
string
Beschreibung
Die Faxnummer.
Name
website
Typ
string
Beschreibung
Die Website.
Name
address
Typ
object
Beschreibung
Die Postanschrift, mit street, postalCode, city und country (ein Code aus zwei Buchstaben wie de).
Name
text
Typ
string
Beschreibung
Die öffentliche Beschreibung der Veranstalter:in.
Name
logo
Typ
string
Beschreibung
Die URL des Logos der Veranstalter:in.
Name
offersCount
Typ
integer
Beschreibung
Die Zahl der Angebote dieser Veranstalter:in, über alle Saisons.
Name
members
Typ
reference[]
Zugriff
nur Admins
Beschreibung
Die Konten, die Mitglieder des Veranstalter-Profils sind. Siehe Ein Mitglied hinzufügen und Veranstalter-Einladungen.
Name
createdAt
Typ
timestamp
Beschreibung
Wann das Veranstalter-Profil angelegt wurde.

GET/hosts

Alle Veranstalter:innen abrufen

Liefert eine Seite mit Veranstalter:innen, nach Namen sortiert. Admins sehen alle. Veranstalter:innen sehen die Veranstalter-Profile, deren Mitglied sie sind.

Optionale Filter

Name
q
Typ
string
Beschreibung
Nur Veranstalter:innen, deren Name oder E-Mail-Adresse diesen Text enthält.
Name
edition
Typ
string
Beschreibung
Nur Veranstalter:innen mit einem Angebot in dieser Saison (UUID oder Alias).
Name
page, itemsPerPage
Typ
integer
Beschreibung
Siehe Paginierung.

GET/hosts

curl "https://example.fepli.eu/api/hosts?edition=herbstferien-2026" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Antwort

[
  {
    "uuid": "01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02",
    "name": "Stadtjugendring Elmsbrück e.V.",
    "alias": "stadtjugendring-elmsbrueck",
    "email": "info@sjr.example.fepli.eu",
    "phone": "0123 456780",
    "website": "https://sjr.example.fepli.eu",
    "address": {
      "street": "Jugendweg 4",
      "postalCode": "12345",
      "city": "Elmsbrück",
      "country": "de"
    },
    "text": "Der Stadtjugendring ist der Dachverband der Jugendverbände in Elmsbrück.",
    "logo": "https://example.fepli.eu/files/logos/sjr-elmsbrueck.png",
    "offersCount": 23,
    "members": [
      {
        "uuid": "0190f1e2-3a4b-7c5d-8e6f-7a8b9c0d1e15",
        "name": "Jonas Becker"
      }
    ],
    "createdAt": "2024-02-19T11:05:31+01:00"
  }
]

GET/hosts/{uuid}

Eine Veranstalter:in abrufen

Liefert eine Veranstalter:in. Veranstalter:innen können nur die Veranstalter-Profile abrufen, deren Mitglied sie sind. Jedes andere ist ein 404.

GET/hosts/{uuid}

curl https://example.fepli.eu/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/hosts

Eine Veranstalter:in anlegen

Legt eine Veranstalter:in an. Nur für Admins. Der Alias entsteht aus dem Namen.

Um Mitglieder hinzuzufügen, fügen Sie ihre Konten hinzu oder laden Sie sie per E-Mail ein.

Pflichtattribute

Name
name
Typ
string
Beschreibung
Der Name der Veranstalter:in, bis zu 255 Zeichen.

Optionale Attribute

Name
email
Typ
string
Beschreibung
Eine gültige E-Mail-Adresse.
Name
phone, mobile, fax
Typ
string
Beschreibung
Jeweils bis zu 64 Zeichen.
Name
website
Typ
string
Beschreibung
Eine vollständige URL, zum Beispiel https://example.org.
Name
address
Typ
object
Beschreibung
street, postalCode, city und country (zwei Buchstaben, Standard: de).
Name
text
Typ
string
Beschreibung
Die öffentliche Beschreibung.

POST/hosts

curl -X POST https://example.fepli.eu/api/hosts \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunstschule Elmsbrück",
    "email": "kontakt@kunstschule.example.fepli.eu",
    "website": "https://kunstschule.example.fepli.eu",
    "address": {
      "street": "Atelierstraße 7",
      "postalCode": "12345",
      "city": "Elmsbrück"
    }
  }'

Die Antwort (201 Created) enthält die neue Veranstalter:in.

PATCH/hosts/{uuid}

Eine Veranstalter:in ändern

Ändert eine Veranstalter:in. Admins können jede ändern, Veranstalter:innen ihre eigene. Die Attribute sind dieselben wie beim Anlegen. Senden Sie nur, was Sie ändern möchten. Ein leerer Body ist ein 422.

address wird als Ganzes ersetzt: Senden Sie alle Felder, denn die Felder, die Sie weglassen, werden geleert (und country fällt auf de zurück). "address": null entfernt die Adresse.

PATCH/hosts/{uuid}

curl -X PATCH https://example.fepli.eu/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0123 456789", "fax": null}'

DELETE/hosts/{uuid}

Eine Veranstalter:in löschen

Löscht eine Veranstalter:in. Nur für Admins. Antwortet mit 204 No Content.

Eine Veranstalter:in, die noch Angebote hat, lässt sich nicht löschen (409). Verschieben Sie die Angebote zu einer anderen Veranstalter:in oder löschen Sie sie zuerst.

DELETE/hosts/{uuid}

curl -X DELETE https://example.fepli.eu/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/hosts/{uuid}/add-member

Ein Mitglied hinzufügen

Macht ein bestehendes Konto sofort zum Mitglied des Veranstalter-Profils, wie es das Admin-Panel tut, wenn es ein Konto einem Veranstalter-Profil zuordnet. Nur für Admins. Es gibt keine Einladung und keine E-Mail: Die Person findet das Veranstalter-Profil bei der nächsten Anmeldung im Admin-Panel. Das Konto erhält ROLE_HOST, falls es sie nicht hatte, genau wie beim Setzen von hosts am Konto. Antwortet mit 200 OK und dem Veranstalter-Profil, dessen members jetzt das Konto enthalten.

Um jemanden zu fragen, der selbst entscheiden soll oder noch kein Konto hat, senden Sie stattdessen eine Einladung.

Ein unbekanntes Konto ist ein 422. Ein Konto, das Sie nicht ändern dürfen, ist ein 403: Für das Konto eines Admins braucht es einen Super-Admin, und Konten, deren personenbezogene Daten für Sie maskiert sind, lassen sich nicht ändern. Ein Konto, das schon Mitglied ist, ist ein 409.

Pflichtattribute

Name
account
Typ
string
Beschreibung
Das Konto, das hinzugefügt wird, als UUID oder E-Mail-Adresse.

POST/hosts/{uuid}/add-member

curl -X POST https://example.fepli.eu/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/add-member \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account": "m.schneider@kunstschule.example.fepli.eu"}'

Antwort (Auszug)

{
  "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
  "name": "Kunstschule Elmsbrück",
  "members": [
    {
      "uuid": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21",
      "name": "Mira Schneider"
    }
  ],
  "…": "…"
}

POST/hosts/{uuid}/remove-member

Ein Mitglied entfernen

Beendet den Zugriff eines Kontos auf das Veranstalter-Profil, wie Zugriff entziehen im Reiter Team des Veranstalter-Profils und Zuordnung entfernen am Konto im Admin-Panel. Nur für Admins. Das Konto ist dann kein Mitglied mehr und verliert die einzelnen Angebote dieses Veranstalter-Profils, die mit ihm geteilt wurden (sharedOffers). Sein Zugriff auf andere Veranstalter-Profile bleibt bestehen, ebenso ROLE_HOST. Niemand wird benachrichtigt. Antwortet mit 200 OK und dem Veranstalter-Profil.

Ein unbekanntes Konto ist ein 422, ein Konto, das Sie nicht ändern dürfen, ein 403. Ein Konto, das weder Mitglied dieses Veranstalter-Profils ist noch ein geteiltes Angebot davon hat, ist ein 409.

Pflichtattribute

Name
account
Typ
string
Beschreibung
Das Konto, das entfernt wird, als UUID oder E-Mail-Adresse.

POST/hosts/{uuid}/remove-member

curl -X POST https://example.fepli.eu/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/remove-member \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21"}'