Styleguide:Techn. Integration via API

Aus Imperia Support Wiki

ENGLISH VERSION

API-Integrationen werden bei BerlinOnline / Berlin.de nur im Ausnahmefall durchgeführt. Dieses muss explizit im Kooperationsvertrag geregelt sein, da diese Art der Integration auf Seiten von B.de / BO größeren Aufwand erzeugt.

Bedingungen

Folgende Bedingungen müssen von Ihnen erfüllt sein:

  • Sie haben eine API, die XML oder JSON als Ausgabe hat (unter keinen Umständen HTML oder Javascript).
  • Ihre API ist via HTTP ansprechbar. Beachten Sie bitte, dass Ihre API über den Port 80 ansprechbar sein muss.
  • Ihre API muss jederzeit valide sein:
    • Wenn Sie XML liefern: Ihr XML muss jederzeit valide sein. Dazu gehört auch die durchgängige Einhaltung eines Zeichensatzes. Zweckmäßigerweise ist dieser UTF-8, dies ist aber nicht zwingend erforderlich. Wir empfehlen den Einsatz von XML-Schemata zur Sicherstellung eines validen Datenformates.
    • Wenn Sie JSON liefern: Ihr JSON muss jederzeit valide und in UTF-8 sein.
    • Auch im Fehlerfall muss es eine aussagekräftige Antwort geben, die auch valide sein muss. Der Type der Fehlermeldungen muss dem der regulären API entsprechen, d.h. für eine JSON-API auch JSON-Fehlermeldungen.
  • Ihre API ist gut dokumentiert. Es existiert eine umfassende, ausführliche API-Dokumentation und ein Ansprechpartner für Rückfragen.
  • Die Dokumentation muss mit dem tatsächlichen Verhalten übereinstimmen.
  • Ihre API muss in Funktionsumfang und Funktionsweise stabil sein. Änderungen an der API müssen einen Monat vor der eigentlichen Änderungen kommuniziert werden. Größere Änderungen werden durch eine Versionierung asynchron zum Livebetrieb umgesetzt.
  • Ihre API muss schnell und zuverlässig antworten. Eine langsame API kann zu kaskadierenden Fehlern führen. Ein Connect muss in maximal 3 Sekunden erledigt sein, und die Response darf auf keinen Fall länger als 20 Sekunden dauern, muss im Regelfall aber weit darunter antworten. Die API als solche muss eine Verfügbarkeit von mindestens 99% pro Woche haben.

Wichtige Einschränkungen

  • Ihre API darf nicht nur unter der Voraussetzung arbeiten, die uns dazu zwingt, Skripte von Ihnen (z.B. PHP, Perl, Javascript, Java, o.ä.) auf unseren Server zu kopieren.
  • Ihre API darf sich nur im Ausnahmefall auf Wertelisten verlassen, die nicht über die API bezogen werden können. Diese Wertelisten dürfen nicht öfter als einmal im Quartal erneuert werden. Die Wertelisten dürfen CSV, JSON oder XML beinhalten.

Bitte haben Sie Verständnis dafür, dass diese Punkte unbedingt erfüllt sein müssen.

Hinweise

Folgende Features sollten bei APIs bedacht werden:

  • Ergebnisse sollten seitenweise abrufbar sein. Ähnlich der Funktion von MySQL-LIMIT sollten Sie eine teilweise Ausgabe von Ergebnissen erlauben, so dass wir in den Ergebnissen "blättern" können. Gleichzeitig ist es dann aber sinnvoll, immer die Gesamtzahl an möglichen Ergebnissen mitzuliefern, so dass wir z.B. folgende Aussage bilden können: "Sie sehen Eintrag 1-20 von 132 Ergebnissen".
  • Ergebnislistings sollten über alle relevanten Felder sortierbar sein.

Vorgehen

  • Sie stellen uns eine API-Dokumentation und die URL Ihrer API zur Verfügung. Wenn wir Partner-IDs benötigen, bitten wir darum, diese zeitgleich mit der URL zur Verfügung zu stellen, damit wir gleich unter Live-Bedingungen entwickeln können.
  • Wir bauen die Anwendung, die dann auf der API aufsetzt, und nennen Ihnen eine URL, unter der Sie den Entwicklungsstand sehen und beobachten können.
  • In Absprache wird die Anwendung dann final angepasst und von uns live geschaltet.

Vorteile

Mit einer XML-API müssen Sie sich um die Gestaltung des Contents keine Gedanken machen, da BerlinOnline die Anpassung für Sie übernimmt.