Versionierung und Kompatibilität

Die öffentliche Feedivo-API ist derzeit unter /api/v1 erreichbar. Verwende für eigene Integrationen ausschließlich diese dokumentierte Basisadresse:

https://feedivo.de/api/v1

Der Versionsabschnitt ist die Vertragsgrenze für grundlegende, nicht rückwärtskompatible Änderungen. Aktuell gibt es keine weitere öffentliche API-Version.

Öffentlicher Vertrag#

Zum dokumentierten API-v1-Vertrag gehören:

• /health
• /me
• /feeds
• /feeds/{uuid}
• /feeds/{uuid}/posts
• /feeds/{uuid}/posts/{postId}

Nur die hier aufgeführten öffentlichen Endpunkte sind für eigene Clients vorgesehen.

Robuste JSON-Verarbeitung#

Ein kompatibler Client sollte:

• unbekannte zusätzliche Objektfelder ignorieren
• bekannte Pflichtfelder und deren Typen weiterhin validieren
• unbekannte errors[].code anhand des HTTP-Status behandeln
• bei neuen Enum-Werten eine sichere Standarddarstellung verwenden
• nicht von der Reihenfolge der JSON-Felder abhängen
• errors immer als Array lesen, auch wenn es heute höchstens einen Eintrag enthält
• message nur anzeigen, aber nie als Steuerwert verwenden

Unbekannte Plattform-, Medien- oder Darstellungswerte dürfen nicht die gesamte Synchronisierung abbrechen. Zeige den Inhalt beispielsweise mit einem neutralen Plattformhinweis oder einem schlichten Kartenlayout an und protokolliere den unbekannten Wert für eine spätere Anpassung.

Streng bei beschädigten Antworten#

Vorwärtskompatibilität bedeutet nicht, jede Antwort ungeprüft zu übernehmen. Fehlen Pflichtfelder wie der API-Umschlag oder ist eine erwartete Liste kein Array, gilt die Antwort als unlesbar. Behalte dann deinen letzten gültigen lokalen Stand und wiederhole den Abruf später.

Insbesondere dürfen folgende Ereignisse niemals als leerer Feed interpretiert werden:

• Netzwerk- oder Zeitüberschreitungsfehler
• 5xx- oder 429-Antworten
• ungültiges JSON
• ein unerwarteter Antwortaufbau
• ein abgebrochener Cursor-Durchlauf

Empfohlene Integrationsprüfungen#

1. Teste Erfolg, 304, 401, 403, 404, 422, 429 und 5xx getrennt.
2. Ergänze in Testantworten ein unbekanntes Feld und einen unbekannten Enum-Wert.
3. Prüfe, dass ein fehlgeschlagener Abruf keine lokalen Daten entfernt.
4. Prüfe einen vollständigen Cursor-Durchlauf mit mehreren Seiten.
5. Übermittle Name und Version deines Clients über X-Feedivo-Client.

Für den ersten vollständigen Ablauf siehe Schnellstart mit der Feedivo-API.