Flyo Importer: Anforderungen an API-Quellen

Dieses Dokument beschreibt, welche Anforderungen eine API-Quelle erfüllen muss, damit der Flyo Importer die Daten zuverlässig verarbeiten kann.

Zusammenfassung

Als Quelle sind ausschließlich API-URLs über HTTP(S) erlaubt.

Mindestanforderungen:

• Eine erreichbare HTTP(S)-API-URL.
• Ein gültiger JSON-Content-Type.
• Eine nicht-leere Liste von Datensätzen (Rows) im Response-Body.
• Eine stabile, eindeutige Datensatz-ID, die auf source_id gemappt wird.

1. Anforderungen an URL und Response

Pflicht

• Die konfigurierte Source-URL muss eine gültige URL sein.
• Der Request muss mit einem erfolgreichen HTTP-Status antworten.
• Der Response-Body muss dem deklarierten Content-Type entsprechen.

Unterstützte Content-Types

• application/json (empfohlen)
• text/json

Wenn ein anderer Typ zurückgegeben wird (zum Beispiel application/xml), wird der Import abgelehnt.

2. Anforderungen an das JSON-Format

Pflicht

• Der oberste JSON-Wert muss ein nicht-leeres Array sein.
• Jede Zeile muss ein Objekt (bzw. eine assoziative Struktur) sein.
• Das erste Objekt muss mindestens ein Property enthalten (wird zur Spaltenerkennung verwendet).

Nicht erlaubt

• Leere JSON-Arrays ([]).
• Arrays mit primitiven Werten (zum Beispiel ["a", "b"]).
• Ein einzelnes Objekt (zum Beispiel { "id": 1 }) statt eines Arrays.

Beispiel (gültig)

[
  {
    "external_id": "evt-1001",
    "title": "Summer Festival",
    "starts_at": 1712455200,
    "image": "https://cdn.example.org/images/festival.jpg"
  },
  {
    "external_id": "evt-1002",
    "title": "Autumn Market",
    "starts_at": "2026-10-12T09:30:00.000Z",
    "image": "https://cdn.example.org/images/market.jpg"
  }
]

3. Pagination für JSON-APIs

JSON-Quellen können HTTP-Link-Header für Pagination verwenden.

Unterstütztes Verhalten

• Flyo folgt Link-Header-Einträgen mit rel="next".
• Alle Seiten werden zu einem Import-Ergebnis zusammengeführt.

Erwartetes Header-Beispiel

Link: <https://api.example.com/events?page=2>; rel="next", <https://api.example.com/events?page=10>; rel="last"

Wichtige Limits und Abbruchbedingungen

• Es werden maximal 100 Seiten verfolgt.
• Die Pagination stoppt, wenn:
  • keine rel="next"-URL vorhanden ist,
  • die nächste URL identisch zur aktuellen URL ist,
  • der nächste Request fehlschlägt,
  • die nächste Seite ungültiges JSON liefert,
  • die nächste Seite ein leeres Array ist.

4. Mapping-Pflicht: source_id

source_id ist Pflicht für die Importsynchronisierung (Insert/Update/Unchanged-Erkennung).

Pflicht

• Deine Mapping-Konfiguration muss ein Zielattribut source_id enthalten.
• Der aufgelöste Wert sollte pro Quell-Datensatz ein stabiler, eindeutiger String sein.

Empfohlen

• source_id kurz und stabil halten (aktuell sind maximal 32 Zeichen durch den Validator sinnvoll).
• Dieselbe source_id nie für unterschiedliche Datensätze wiederverwenden.
• Keine zufälligen IDs pro Lauf erzeugen.

Wenn source_id im Mapping fehlt, kann der Import Datensätze nicht korrekt synchronisieren.

5. Normalisierung und Validierung von Werten

Während des Mappings werden Werte je nach Feldtyp transformiert.

Text und Textarea

• HTML-Tags werden entfernt.
• Der verbleibende Text wird HTML-escaped.

Empfehlung: Wenn möglich, sauberen Plain Text liefern.

Datumsfelder (datepicker)

Akzeptierte Eingaben:

• Unix-Timestamp (numerisch)
• Parsebarer Datumsstring

Gespeichertes Format:

• YYYY-MM-DD

Empfehlung: Unix-Timestamps oder ISO-ähnliche Datumsstrings senden, um Locale-Mehrdeutigkeiten zu vermeiden.

Datetime-Felder (datetimepicker)

Akzeptierte Eingaben:

• Unix-Timestamp (numerisch)
• ISO-8601-Datetime-String

Empfehlung:

• Bevorzugt ISO-8601-UTC mit Millisekunden verwenden, zum Beispiel 2026-04-12T15:30:00.000Z.
• Unix-Timestamps werden ebenfalls unterstützt und sind sinnvoll, wenn dein System timestamp-basiert ist.

Datei- und Bildfelder

Pflicht:

• Der Wert muss eine gültige URL sein.
• Die URL muss auf eine herunterladbare Datei zeigen.

Empfehlung:

• Direkte HTTP(S)-URLs auf die Binärdatei verwenden.
• Sicherstellen, dass die Datei für die Importer-Runtime erreichbar ist.
• Ablaufende URLs vermeiden, außer der Import läuft garantiert innerhalb der Gültigkeit.

Wenn URL-Validierung oder Dateidownload fehlschlägt, enthält die Zeile Validierungsfehler.

6. Best Practices für stabile Delta-Imports

Zur Minimierung unnötiger Updates und Fehler:

• Feldnamen und Payload-Struktur stabil halten.
• Mapping nur ändern, wenn eine echte Mapping-Änderung gewünscht ist.
• Für gemappte Felder immer deterministische Werte liefern.
• Sicherstellen, dass Quell-Datensätze vollständig sind (Pflicht-Zielattribute sollten nicht leer sein).
• Erst mit kleinem Datensatz testen, dann skalieren.

7. Troubleshooting-Checkliste

Wenn Importe fehlschlagen oder unerwartet laufen, prüfen:

• URL ist gültig und erreichbar.
• HTTP-Response ist erfolgreich.
• Content-Type ist einer der unterstützten MIME-Typen.
• JSON-Top-Level ist ein nicht-leeres Array.
• Mapping enthält source_id.
• source_id-Werte sind eindeutig und stabil.
• Datei-/Bildwerte sind gültige, erreichbare URLs.
• Date-/Datetime-Werte folgen den empfohlenen Formaten.

8. Quick Provider Contract (Copy/Paste)

Diesen Abschnitt kannst du direkt an Datenlieferanten weitergeben:

• Endpoint liefert application/json (bevorzugt) oder text/json.
• Body ist ein nicht-leeres Array von Objekten.
• Jedes Objekt enthält ein stabiles, eindeutiges ID-Feld (für source_id-Mapping).
• Pagination (falls verwendet) liefert RFC-5988-Link-Header mit rel="next".
• Datei-/Bildfelder enthalten gültige HTTP(S)-URLs.
• Datumswerte sind Unix-Timestamps oder parsebare Datumsstrings.
• Datetime-Werte sind Unix-Timestamps oder ISO-8601-UTC-Strings.