Dokumentation der Webschnittstelle

Die Webschnittstelle ist nichts anderes, als ein Script (beispielsweise in PHP geschrieben) auf den Servern der Partnerseiten, welches es ermöglicht passende Suchergebnisse auf den dortigen Datenbestände zu ermitteln. Auf dieser Seite wird der genaue Ablauf dieses Vorhangs beschrieben.

Übermittlung der Anfrage

Das Script muss auf ihrem Server abgelegt werden und vom Internet aus erreichbar sein. Bei einem Suchlauf wird nun dessen URL aufgerufen und die Suchparameter via GET-Methode UTF-8 kodiert übermittelt. Ein solcher Aufruf könnte z.B. so aussehen:

http://www.lyric.tld/songvista.php?artist=Madonna&title=Ray%20of%20light&type=all

Parameterübersicht

Parameter	Bedeutung	Mögliche Werte
artist	Interpret	alles*
title	Titel	alles*
type	Art der Ergebnisse	lyric (Songtext) translation (Übersetzung) music (Chords,Tabs oder Noten) all (alles)

* enthält keine Steuerzeichen (\n, \r, \t)

Ausgabeformatierung

Das Script antwortet im einfachen plain/text-Format und gibt die Ergebnisse der lokalen Suche zeilenweise (bzw. durch das Steuerzeichen "\n" getrennt), und ebenfalls UTF-8 kodiert, in dieser Form aus:

artist|title|type|URL

Feldübersicht

Feld	Bedeutung	Mögliche Werte
artist	Interpret	alles*
title	Titel	alles*
type	Art des Datensatzes	lyric (Songtext) translation_de** (Übersetzung) music (Chords,Tabs oder Noten)
URL	Link zum Datensatz	muss mit http:// beginnen*

* Das Zeichen | muss gegen __line__ ersetzt werden, es sind keine Steuerzeichen (\n, \r, \t) erlaubt
** nach dem Unterstrich wird die Sprache der Übersetzung angegeben (z.B. de, en, es, fr)

Eine typische Anfrage nach Songtexten von "Madonna" würde also z.B. so beantwortet werden:

Madonna|Ray of light|lyric|http://www.lyric.tld/madonna/ray_of_light.html
Madonna|Get together|lyric|http://www.lyric.tld/madonna/get_together.html
Madonna|Like it or not|lyric|http://www.lyric.tld/madonna/like_it_or_not.html

Die Anzahl der Ergebnisse, sollte auf 50 begrenzt werden, denn nur so viele Zeilen werden auch von Songvista berücksichtigt.

Vorteile

- Besucher haben immer Zugriff auf aktuellste Ergebnisse
- Finden Partnerseiten, auch wenn sie ihnen vorher unbekannt war
- Keine Synchronisation der Datenbestände nötig
- Schnelle Suche auf großen Datenmengen durch Verteilung der Anfragen
- Volle Kontrolle, da Schnittstelle selbst verwaltet und implementiert wird
- Schnittstelle funktioniert auch bei Layout- oder Schemaveränderungen auf der Partnerseite
- Sie kann, falls gewünscht, auch von anderen Seiten genutzt werden

Nachteile

- Partnerseiten beantworten Suchanfragen ggf. "umsonst" (Besucher geht zu anderer Seite)
- es entsteht Traffic (ca. 5 - 10 MB pro Tag)

Anmerkungen zur Nutzung der Schnittstelle

Antwortet eine Schnittstelle nicht innerhalb von 10 Sekunden, so wird die Anfrage abgebrochen (timeout). Songvista verfügt über eine integrierte Lastkontrolle, die verhindert, dass eine Partnerseite durch ihre Webschnittstelle zu sehr ausgelastet wird. Zum einen werden nie mehr als 10 Suchanfragen gleichzeitig gestellt. Zum anderen werden Schnittstellen, die nicht rechtzeitig geantwortet haben, bei den nächsten Suchdruchläufen ausgelassen. Je öfter dies geschieht, desto länger wird die betreffende Schnittstelle nicht mehr angesprochen.
Zusätzlich werden die Ergebnisse zwischengespeichert (Cache). Eine bereits vor kurzem gestellte Suchanfrage wird damit nicht wiederholt an die Webschnittstelle weitergeleitet.

Die Ergebnisse werden in der selben Reihenfolge angezeigt, in der sie ausgegeben wurden und sollten daher vorsortiert werden.

Beispielimplementierung

Hier finden sie eine exemplarische Implementierung der Schnittestelle für PHP ab Version 4.1.0. Sie stellt bereits die wesentliche Funktionalität bereit. In der Regel sollte lediglich die Datenbankanbindung angepasst werden müssen. Das Script darf nach belieben verändert werden.

Anmerkung zur Beispielimplementierung:
Sollte ihre Datenbank nicht mit der UTF8-Codierung arbeiten, verwenden sie bitte die Funktion utf8_decode() für die Eingaben und utf8_encode() für die Ausgaben.

Gerne passe ich das Script auch selbst an. Dazu benötige ich lediglich das Schema ihrer Datenbank.