Dokumentation der Webschnittstelle

Die Webschnittstelle (API) ist nichts anderes, als ein Script 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. Zudem finden sie hier eine Beispielimplementierung für PHP.

Ü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 HTTP-GET und 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 Texte ihrer Seite
- Keine Synchronisation der Datenbestände nötig
- User finden ihre Seite, auch wenn sie ihnen zuvor unbekannt war
- Schnelle Suche auf großen Datenmengen durch Verteilung der Anfragen
- Volle Kontrolle, da Schnittstelle selbst verwaltet und implementiert wird
- 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. Es werden nie mehr als 10 Suchanfragen innerhalb von 5 Sekunden gestellt. 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 Schnittstelle 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:
Kodieren sie bitte die Ein- und Ausgaben entsprechend um, falls ihre Datenbank nicht mit der UTF8-Kodierung arbeitet.

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