EntwicklerAPI-Ressourcen

Kategorien

Kategorien ordnen Angebote nach ihrem Thema, etwa Sport, Kunst oder Natur. Die Ressource heißt in der API offer-categories. Mit ihr bauen Sie einen Kategoriefilter für Ihre Website oder ordnen neue Angebote ein.

Endpunkte

GET/offer-categoriesAlle Kategorien abrufen
GET/offer-categories/{uuid}Eine Kategorie abrufen
POST/offer-categoriesEine Kategorie anlegen
PATCH/offer-categories/{uuid}Eine Kategorie ändern
DELETE/offer-categories/{uuid}Eine Kategorie löschen

Alle mit ROLE_HOST können die Kategorien lesen. Anlegen, Ändern und Löschen braucht ROLE_SUPER_ADMIN, wie im Admin-Panel, wo sie unter Einstellungen → Angebote gepflegt werden.

Das Modell der Kategorie

Name
uuid
Typ
string
Beschreibung
Die Kennung der Kategorie.
Name
name
Typ
string
Beschreibung
Der Name der Kategorie.
Name
alias
Typ
string
Beschreibung
Ein URL-tauglicher Name. Er wird überall akzeptiert, wo eine Kategorie genannt wird, etwa in ?category=sport-bewegung. Der Kategoriefilter auf der Website verwendet ihn in seinen URLs.

GET/offer-categories

Alle Kategorien abrufen

Liefert jede Kategorie, sortiert nach Name. Die Liste ist nicht paginiert.

Um ein Angebot einer Kategorie zuzuordnen, senden Sie ihre uuid oder ihren alias in den categories des Angebots.

Anonyme Aufrufer können diesen Endpunkt nicht verwenden, aber jedes öffentliche Angebot enthält seine Kategorien mit uuid, name und alias.

GET/offer-categories

curl https://example.fepli.eu/api/offer-categories \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Antwort

[
  {
    "uuid": "018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19",
    "name": "Kreativ",
    "alias": "kreativ"
  },
  {
    "uuid": "018f2c3d-6b7c-7d8e-9f0a-1b2c3d4e5f20",
    "name": "Natur & Umwelt",
    "alias": "natur-umwelt"
  },
  {
    "uuid": "018f2c3d-4e5f-7a6b-8c7d-9e0f1a2b3c12",
    "name": "Sport & Bewegung",
    "alias": "sport-bewegung"
  }
]

GET/offer-categories/{uuid}

Eine Kategorie abrufen

Liefert eine Kategorie. Der Pfad erwartet die UUID, nicht den Alias.

GET/offer-categories/{uuid}

curl https://example.fepli.eu/api/offer-categories/018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Antwort

{
  "uuid": "018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19",
  "name": "Kreativ",
  "alias": "kreativ"
}

POST/offer-categories

Eine Kategorie anlegen

Legt eine Kategorie an. Nur Super-Admins.

Ohne alias wird er aus dem Namen gebildet: Aus Musik & Tanz wird musik-tanz. Hat schon eine andere Kategorie diesen Alias, lautet die Antwort 409. Senden Sie dann einen eigenen alias.

Pflichtattribute

Name
name
Typ
string
Beschreibung
Der Name, bis zu 255 Zeichen.

Optionale Attribute

Name
alias
Typ
string
Beschreibung
Kleinbuchstaben, Ziffern und Bindestriche, etwa musik-tanz. Alles andere ergibt ein 422. Er darf nicht der Alias einer anderen Kategorie sein (409).

POST/offer-categories

curl -X POST https://example.fepli.eu/api/offer-categories \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Musik & Tanz"}'

Antwort (201 Created)

{
  "uuid": "0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21",
  "name": "Musik & Tanz",
  "alias": "musik-tanz"
}

PATCH/offer-categories/{uuid}

Eine Kategorie ändern

Ändert den name oder den alias einer Kategorie. Nur Super-Admins. Die Attribute und ihre Regeln sind dieselben wie beim Anlegen einer Kategorie. Senden Sie nur, was sich ändern soll. Ein leerer Body ergibt ein 422.

Beim Umbenennen behält die Kategorie ihren Alias. Der Alias ist Teil der URLs des Kategoriefilters auf der Website und jedes Links und jeder Integration, die ?category= verwenden. Er ändert sich deshalb nur, wenn Sie einen neuen alias senden. Mit "alias": null wird aus dem aktuellen Namen ein neuer gebildet.

PATCH/offer-categories/{uuid}

curl -X PATCH https://example.fepli.eu/api/offer-categories/0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Musik, Tanz & Theater"}'

Antwort

{
  "uuid": "0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21",
  "name": "Musik, Tanz & Theater",
  "alias": "musik-tanz"
}

DELETE/offer-categories/{uuid}

Eine Kategorie löschen

Löscht eine Kategorie. Nur Super-Admins. Die Antwort ist 204 No Content.

Solange Angebote dieser Kategorie zugeordnet sind, lässt sie sich nicht löschen (409). Die Meldung nennt, wie viele es sind. Entfernen Sie die Kategorie zuerst aus diesen Angeboten, indem Sie deren categories ohne sie senden.

DELETE/offer-categories/{uuid}

curl -X DELETE https://example.fepli.eu/api/offer-categories/0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21 \
  -H "Authorization: Bearer $FEPLI_TOKEN"