EntwicklerAnwendungsfälle

Umstieg von der Angebots-API

Frühere Versionen der fepli API kannten eine einzige Ressource: Angebote. Die API deckt jetzt das ganze Admin-Panel ab, und der Endpunkt der Angebote wurde dabei neu gebaut. Wenn Sie ihn schon vorher genutzt haben, steht auf dieser Seite, was Sie ändern müssen.

Checkliste

Verwenden Sie den Endpunkt unter Einstellungen → Integrationen → API als Basis-URL (siehe Schnellstart).
Speichern Sie Angebote mit der uuid, nicht mit der numerischen id, und rufen Sie einzelne Angebote mit /offers/{uuid} ab.
Benennen Sie Ihre Filter um (siehe unten).
Lesen Sie status als Liste und edition und hosts als Referenzen.
Behandeln Sie fehlende Felder wie null.
Rufen Sie mit page und itemsPerPage so lange Seiten ab, bis eine Seite kürzer ist. Verlassen Sie sich nicht auf einen Link-Header.
Ein persönliches API-Token funktioniert für Angebote weiter. Für alles andere erstellen Sie ein neues Token, am besten für einen Service-Account.

Basis-URL

Die API antwortet unter /api auf der Domain des Admin-Panels oder an der Wurzel der eigenen API-Domain der Organisation, falls sie eine hat. Die genaue Adresse steht unter Einstellungen → Integrationen → API → Endpunkt. Die Pfade in dieser Dokumentation sind relativ dazu: GET /offers bedeutet GET https://example.fepli.eu/api/offers.

Kennungen

Angebote werden über eine UUID identifiziert, die jedem Aufrufer als uuid geliefert wird. Die numerische id gibt es nicht mehr, ebenso wenig /api/offers/{id}:

Vorher	Jetzt
`GET /api/offers/42`	`GET /offers/0192a4f1-6e3b-7c85-b1d2-8f4e6a9c3b03`
`id` (nur authentifizierte Aufrufer)	`uuid` (alle)

Wenn Sie numerische IDs gespeichert haben, ordnen Sie Ihre Datensätze einmal über alias oder url zu und wechseln dann zur uuid.

Felder

Feld	Vorher	Jetzt
`status`	ein Objekt aus Status und Zeitstempel, nur authentifiziert	eine Liste von Status, z. B. `["published"]`, für alle
`edition`	ein Objekt mit `name`, nur authentifiziert	eine Referenz mit `uuid`, `name`, `alias`, für alle
`hosts`	Objekte mit `name`	Referenzen mit `uuid`, `name`, `alias`
`publish`	`public` oder `private_link`, für alle	`public` oder `private_link`, nur authentifiziert
`createdAt`, `modifiedAt`	nur authentifiziert	alle
`minParticipants`, `maxParticipants`	nur authentifiziert	alle
`dates[]`	`begin`, `end`	zusätzlich `uuid` und, bei wiederkehrenden Terminen, `recurrence`
neu	–	`teaser`, `vacancies`, `fullyBooked`, `categories` für alle; `comment`, `contact`, `attendances`, `applicationQuestions`, `transitions` und mehr mit Token

Felder ohne Wert werden jetzt weggelassen, statt als null geliefert zu werden. Aus "applyText": null wird gar kein Schlüssel applyText.

Filter

Die Filter wurden vereinfacht. Saisons und Veranstalter:innen geben Sie in einem einzigen Parameter als UUID oder Alias an:

Vorher	Jetzt
`edition.id`, `edition.alias`, `edition.name`	`edition` (UUID oder Alias)
`hosts.alias`, `hosts.name`	`host` (UUID oder Alias)
`dates.begin[after]`	`from`
`dates.begin[before]`	`until`
`dates.begin[strictly_after]`, `dates.begin[strictly_before]`	`from`, `until` (beide schließen den angegebenen Tag ein)
`fee[lte]`, `fee[gte]`, `fee[lt]`, `fee[gt]`, `fee[between]`	entfernt. Filtern Sie `fee` auf Ihrer Seite.
`meetingPoint`	entfernt. Durchsuchen Sie den Namen mit `q` oder filtern Sie auf Ihrer Seite.
–	neu: `q`, `status`, `category`, `modifiedSince`, `sort`, `order`

Alle Filter stehen unter Alle Angebote abrufen.

Paginierung

page funktioniert wie bisher, und itemsPerPage bestimmt jetzt die Seitengröße, bis zu 200. Die Antwort ist ein einfaches JSON-Array. Die frühere Dokumentation beschrieb einen Link-Header mit first, next und last; die API sendet keinen. Fordern Sie so lange Seiten an, bis eine weniger Datensätze enthält, als Sie angefordert haben. Siehe Paginierung.

Tokens und Rate-Limits

Persönliche Tokens, die vor der Änderung erstellt wurden, tragen den Scope api:offer:read. Sie funktionieren weiter für GET /offers und GET /offers/{uuid}, sonst für nichts.
Neue Tokens sind nur lesend oder lesend und schreibend und können statt einer Person einem Service-Account gehören.
Mit Token stieg das Rate-Limit von 50 Anfragen pro Stunde auf einen Burst von 300, aufgefüllt mit 100 pro Minute. Anonyme Anfragen bleiben bei 5 pro Stunde und IP-Adresse. Siehe Rate-Limits.

Fehler

Fehler sind weiterhin Problem Details mit type, title, status und detail. Der type ist jetzt ein kurzer Pfad wie /errors/404 statt eines Links auf die HTTP-Spezifikation. Die Meldungen in detail sind genauer, zum Beispiel No offer with this identifier, or none you may see.