Schnellstart
In etwa fünf Minuten senden Sie Ihre erste authentifizierte Anfrage. Sie finden Ihren Endpunkt, rufen die öffentlichen Angebote ab, erstellen ein Token, prüfen seine Rechte und verwenden es.
- 1ohne TokenEndpunkt findenBasis-URL
- 2ohne TokenÖffentliche Anfrage sendenGET /offers
- 3im Admin-PanelToken erstellenFEPLI_TOKEN
- 4mit dem TokenIdentität prüfenGET /me
- 5mit dem TokenToken verwendenGET /search
1. Endpunkt finden
Jede Organisation betreibt ihr eigenes fepli und hat deshalb einen eigenen API-Endpunkt.
Im Standard liegt die API auf dem Host des Admin-Panels unter /api. Wenn Sie das Admin-Panel unter https://example.fepli.eu/admin öffnen, liegt die API unter https://example.fepli.eu/api.
Super-Admins sehen den Endpunkt unter Einstellungen → Integrationen → API in der Zeile Endpunkt. In einer Installation mit einem Mandanten steht dort nur /api. Gemeint ist der Host des Admin-Panels.
Alle Beispiele dieser Dokumentation verwenden https://example.fepli.eu/api als Basis-URL. Pfade wie /offers sind relativ dazu.
Auf derselben Seite der Einstellungen schalten Super-Admins die ganze API mit Schnittstelle aktiv ein und aus. Öffentlicher Zugriff legt fest, ob die veröffentlichten Angebote ohne Token lesbar sind. Eine ausgeschaltete API beantwortet jede Anfrage mit 404.
2. Öffentliche Anfrage senden
Die veröffentlichten Angebote der Saisons, die online sind, lassen sich ohne Token lesen, solange der öffentliche Zugriff eingeschaltet ist. Probieren Sie es aus:
curl https://example.fepli.eu/api/offers
Die Antwort ist ein JSON-Array von Angeboten. Wenn Sie nur Angebote auf einer Website zeigen wollen, lesen Sie hier weiter: Angebote auf Ihrer Website.
3. Token erstellen
Alles Weitere braucht ein Token. Es gibt zwei Arten:
Handelt als Sie, mit Ihren Rollen. Sie erstellen es im Admin-Panel: Öffnen Sie Ihr Benutzermenü und wählen Sie Passwort ändern. Wählen Sie auf der Seite Sicherheit API-Tokens → Neuer API-Token.
Handelt als Service-Account. Das ist eine Maschinenidentität, die nur die Rollen hat, die Sie ihr geben. Verwenden Sie es für alles, was dauerhaft läuft, etwa eine Integration oder eine regelmäßige Auswertung. Super-Admins erstellen es unter Einstellungen → Integrationen → API → Service-Accounts.
Wählen Sie beim Erstellen Nur lesen, wenn Sie keine Daten ändern müssen, und geben Sie dem Token ein Ablaufdatum. fepli zeigt das Token nur einmal. Kopieren Sie es, bewahren Sie es sicher auf und legen Sie es für die folgenden Beispiele in eine Umgebungsvariable:
export FEPLI_TOKEN='svc-…'
4. Identität prüfen
Senden Sie das Token als Bearer-Token im Header Authorization. Beginnen Sie mit GET /me. Die Antwort nennt, wem das Token gehört, welche Rollen es hat und ob es schreiben darf.
curl https://example.fepli.eu/api/me \
-H "Authorization: Bearer $FEPLI_TOKEN"
Bei 401 ist das Token falsch oder abgelaufen, oder es gehört zu einem deaktivierten Service-Account. Siehe Authentifizierung.
5. Token verwenden
Mit einem Token liefert der Endpunkt der Angebote mehr als die veröffentlichten Angebote, und weitere Endpunkte stehen offen.
Zum Beispiel durchsuchen Sie alles, was Ihre Rollen Ihnen zeigen:
Suche
curl "https://example.fepli.eu/api/search?q=Fahrradtour" \
-H "Authorization: Bearer $FEPLI_TOKEN"
Antwort
{
"query": "Fahrradtour",
"offers": [
{
"uuid": "0192a4f1-6e3b-7c85-b1d2-8f4e6a9c3b03",
"name": "Fahrradtour durch den Stadtpark",
"alias": "fahrradtour-durch-den-stadtpark"
}
],
"editions": [],
"participants": [],
"accounts": [],
"hosts": [],
"receipts": []
}
Jede Referenz in einer Antwort trägt eine uuid. Mit ihr rufen Sie den vollständigen Datensatz ab, zum Beispiel mit GET /offers/{uuid}.
Wie es weitergeht
- Authentifizierung: Arten von Tokens, Scopes und was geschieht, wenn die API ein Token ablehnt
- Berechtigungen: welche Rollen welche Endpunkte öffnen
- Konventionen: Kennungen, Datumsangaben, Beträge, Filter und die Regeln für
PATCH - Angebote: die Referenz der meistgenutzten Ressource