API-Dokumentation

Wer-hat-Fotos.net ist als verteilte Suchmaschine konzipiert, die keinen eigenen Bildkatalog pflegt, sondern Suchabfragen in Echtzeit an die angeschlossenen Bildershops weiterleitet. Deren Ergebnisse werden zusammengefasst und an den Suchenden zurückleitet. Jeder angeschlossene Shop muss daher über eine Schnittstelle verfügen, die Suchabfragen von Wer-hat-Fotos.net entgegennimmt und verarbeitet.

Dieses Dokument beschreibt, wie eine Schnittstelle im Detail aussehen muss, damit die Anbindung an Wer-hat-Fotos.net reibungslos funktioniert. Es wendet sich an Entwickler mit Erfahrungen in serverseitiger Skriptprogrammierung. Wenn Sie nicht zu diesem Personenkreis gehören, können Sie entweder auf ein Bildershopsystem mit fertiger Schnittstelle zurückgreifen oder das PHP-Beispielskript nutzen, das am Ende dieses Dokuments beschrieben ist.

Grundsätzliches

Alle Abfragen, die Wer-hat-Fotos.net an die Schnittstelle sendet, werden per HTTP-GET übermittelt. Die URL, unter der die Schnittstelle erreichbar ist, können Sie im Shopprofil einstellen.

Wer-hat-Fotos.net setzt ein Hash-Verfahren ein, um Abfragen zu authentifzieren. Für jede Abfrage wird ein MD5-Hash-Code übermittelt, in dessen Berechnung die jeweiligen Abfrageparameter sowie ein geheimer API-Schlüssel und ein Zeitstempel einfließen. Anhand des Hash-Codes können Sie überprüfen, ob die Abfrage wirklich von Wer-hat-Fotos.net stammt und ob es sich um eine aktuelle Abfrage handelt.

Die Abfragen von Wer-hat-Fotos.net verwenden die folgenden URL-Parameter:

ParameterBedeutung
-cmd

Die Art der Abfrage, die auszuführen ist (siehe nachfolgende Abschnitte). Mögliche Werte sind:

  • count (Gesamtzahl der Bilder)
  • get_index (Verzeichnis aller Stichwörter)
  • list (Liste von Bildern zu einem Suchbegriff)
-q Der Suchbegriff, für den Bilder aufgelistet werden sollen (nur bei list-Abfragen).
-ts Der Zeitpunkt, an dem die Abfrage erstellt wurde. Dieser wird in Form eines Unix-Zeitstempels angegeben, das heißt als Zahl der Sekunden, die seit dem 1.1.1970 um 0:00 Uhr verstrichen sind.
-hash Ein nach dem MD5-Verfahren berechneter Hash-Code aus den ersten drei Parametern (in der hier aufgeführten Reihenfolge) und dem geheimen API-Schlüssel.
callback Funktionsname, der in das Ergebnis einzubinden ist (optional). 

Ist in der URL ein callback-Parameter enthalten, muss das Ergebnis als JavaScript zurückgeliefert werden (Content-Type: text/javascript), ansonsten als Wert im JSON-Format (Content-Type: application/json). Die Beispiele in den folgenden Abschnitten zeigen, wie das im Detail aussehen kann.

Arten von Abfragen

Im folgenden finden Sie die drei Arten von Abfragen näher erläutert, die eine Schnittstelle beantworten können muss.

Gesamtzahl der Bilder (count)

Wer-hat-Fotos.net blendet im Seitenkopf stets die Gesamtzahl der Bilder ein, die zum gegenwärtigen Zeitpunkt durchsucht werden können. Um diese Zahl aktuell zu halten, werden die angeschlossenen Shops regelmäßig nach der Gesamtzahl der von ihnen bereitgestellten Bilder befragt. Die Schnittstelle muss daher bei Bedarf diese Zahl zurückliefern.

Beispielabfrage 1:

http://www.meinbildershop.de/api/index.php?-cmd=count 

Beispielantwort (Content-Type: application/json):

829 

Beispielabfrage 2:

http://www.meinbildershop.de/api/index.php?-cmd=count&callback=xyz 

Beispielantwort (Content-Type: text/javascript):

xyz(829) 

Beachten Sie, dass Zahlen über 999 kein Tausendertrennzeichen enthalten dürfen. Es muss also zum Beispiel 2814 zurückgeliefert werden, und nicht 2.814.

Verzeichnis aller Stichwörter (get_index)

Wer-hat-Fotos.net speichert zu jedem Shop eine Liste der Stichwörter ab, zu denen Bilder existieren. Diese Liste sorgt dafür, dass bei einer Bildsuche nur diejenigen Shops abfragt werden müssen, die auch tatsächlich passendes Bildmaterial enthalten. Die Schnittstelle muss daher bei Bedarf eine Liste aller Stichwörter zurückliefern, zu denen es Bilder gibt.

Beispielabfrage 1:

http://www.meinbildershop.de/api/index.php?-cmd=get_index

Beispielantwort (Content-Type: application/json):

["auto","flugzeug","schiff"] 

Beispielabfrage 2:

http://www.meinbildershop.de/api/index.php?-cmd=get_index&callback=xyz 

Beispielantwort (Content-Type: text/javascript):

xyz(["auto","flugzeug","schiff"]) 

In welcher Reihenfolge die Stichwörter geliefert werden, spielt keine Rolle. Für eine eventuelle Fehlersuche ist es allerdings hilfreich, wenn die Stichwörter alphabetisch sortiert vorliegen.

Liste von Bilder zu einem Suchbegriff (list)

Bei einer Bildsuche prüft Wer-hat-Fotos.net zunächst anhand der globalen Stichwortliste, welche Shops in die Trefferliste aufzunehmen sind. Anschließend wird an jeden dieser Shops eine Abfrage gesendet, die den verwendeten Suchbegriff enthält. Die Schnittstelle muss dann eine Liste von Bildern zurückliefern, die zu dem Suchbegriff passen.

Beispielabfrage 1:

http://www.meinbildershop.de/api/index.php?-cmd=list&-q=flugzeug 

Beispielantwort (Content-Type: application/json):

{ 
"count": "2",
"list": [
{"thumbnail_url": "thumbnails/img_4711.jpg", "image_url": "gallery1/img_4711.html"},
{"thumbnail_url": "thumbnails/img_4712.jpg", "image_url": "gallery1/img_4712.html"}
]
}

Beispielabfrage 2:

http://www.meinbildershop.de/api/index.php?-cmd=list&-q=flugzeug&callback=xyz

Beispielantwort (Content-Type: text/javascript):

xyz( [ "count": "2", "list": [ {...}, {...} ] ) 

Das count-Element muss die Gesamtzahl der Bilder angeben, die gefunden wurden. Das list-Element soll höchstens zehn Einträge enthalten, da in der Trefferliste von Wer-hat-Fotos.net auch höchstens zehn Treffer pro Shop eingeblendet werden. Die zehn Elemente sollten nach dem Zufallsprinzip ausgewählt werden, damit bei einer wiederholten Anfrage (mit gleichem Suchbegriff) eine andere Auswahl zurückgeliefert wird.

Beachten Sie, dass die Schnittstelle auch in der Lage sein muss, einen leeren Suchbegriff zu verarbeiten. In diesem Fall sollen nach dem Zufallsprinzip zehn beliebige Bilder des Shops zurückgeliefert werden. Außerdem sollte das Prozentzeichen als „Wildcard“-Symbol (Platzhalter für eine beliebige Zeichenkette) interpretiert werden.

PHP-Beispielskript

Wenn auf Ihrem Webserver die Skriptsprache PHP unterstützt wird (Version 5.1 oder höher), können Sie mit Hilfe dieses Beispielskripts auf einfache Weise eine Schnittstelle zu Wer-hat-Fotos.net einrichten. Das Skript arbeitet auf Grundlage einer Textdatei (CSV-Format), in der alle Shop-Bilder verzeichnet sind. Es lässt sich aber auch leicht anpassen, um die Bildliste z. B. direkt aus einer mySQL-Datenbank auszulesen.

Installation

  1. Laden Sie das Beispielskript herunter.
  2. Entpacken Sie das Zip-Archiv.
  3. Bereiten Sie die CSV- und die Konfigurationsdatei vor, wie in den nachfolgenden Abschnitten beschrieben.
  4. Laden Sie das api-Verzeichnis mit allen Inhalten auf einen öffentlich zugänglichen Webserver.

CSV-Datei vorbereiten

Damit die Schnittstelle korrekt arbeitet, müssen Sie eine Liste aller Bilder Ihres Shops vorbereiten. Diese Liste muss in Form einer Textdatei im CSV-Format bereitgestellt werden. Jede Zeile entspricht einem Bild und muss folgendermaßen aufgebaut sein:

Thumbnail[tab]Bildseite[tab]Stichwörter

Anstelle von [tab] muss ein Tabulatorzeichen eingefügt werden. Die einzelnen Elemente haben folgende Bedeutung:

ElementBedeutung
Thumbnail URL einer Miniaturansicht des Bildes. Diese Ansicht sollte nicht höher oder breiter als 120 Pixel sein, da Wer-hat-Fotos.net zur Zeit keine automatische Skalierung durchführt.
Bildseite URL der Bilddetailseite. Zu dieser Seite wird ein Besucher geleitet, wenn er auf die Miniaturansicht eines Bildes klickt.
Stichwörter Kommagetrennte Liste der Stichwörter, die dem Bild zugeordnet sind. Um die Lesbarkeit zu erhöhen, dürfen hinter den Kommas zusätzliche Leerzeichen eingefügt werden.

Damit Umlaute und Sonderzeichen in den Stichwörtern korrekt codiert werden, muss die Datei im UTF–8- oder im ISO-8859-1-Zeichensatz gespeichert werden.

Konfigurationsdatei vorbereiten

Die Schnittstelle lässt sich mit Hilfe einer Konfigurationsdatei an die jeweiligen Gegebenheiten anpassen. Eine Beispielkonfigurationsdatei (example_config.php) wird mitgeliefert. Legen Sie eine Kopie dieser Datei unter dem Namen config.php an, und ändern Sie diese entsprechend ab.

Die Konfigurationsparameter haben folgende Bedeutung:

ParameterBedeutung
$config[‘api_key’] API-Schlüssel für den Zugriff auf die Schnittstelle. Hierbei handelt es sich um eine Kette von Buchstaben und Zahlen, die nach dem Zufallsprinzip aneinandergereiht worden sind. Diese Kette sollte 20 bis 40 Zeichen umfassen und muss in Wer-hat-Fotos.net hinterlegt werden, damit der Zugriff funktioniert.
$config[‘request_timeout’] Zahl der Sekunden, für die eine Abfrage gültig bleibt, gerechnet ab dem Zeitpunkt, der in der URL als -ts-Parameter übergeben wird. Der Vorgabewert von 60 braucht normalerweise nicht verändert zu werden.
$config[‘path_to_datafile’] Name der CSV-Datei, in der die Bildliste gespeichert ist. Wenn die Datei nicht im gleichen Verzeichnis liegt wie das Skript, ist der (absolute oder relative) Dateisystempfad anzugeben.
$config[‘utf8_encoding’] Angabe, ob die CSV-Datei im UTF8-Zeichensatz vorliegt oder nicht. Wenn dieser Parameter nicht auf TRUE gesetzt ist, muss die CSV-Datei im ISO-8859-1-Zeichensatz vorliegen.

Shop anmelden und testen

Wenn die Schnittstelle installiert ist, können Sie Ihren Shop bei Wer-hat-Fotos.net anmelden. Gehen Sie dazu folgendermaßen vor:

  1. Loggen Sie sich in Ihr Benutzerkonto bei Wer-hat-Fotos.net ein.
  2. Falls Sie noch keinen Shop angelegt haben, klicken Sie auf "Shop einrichten", ansonsten auf "ändern".
  3. Füllen Sie die Eingabemaske vollständig aus. Aktivieren Sie im Feld Schnittstelle die Option "andere" und tragen Sie im Feld API-URL die Adresse ein, unter der das index.php-Skript Ihrer Schnittstelle erreichbar ist. Als Such-URL können Sie die Adresse eines Skripts eintragen, das eine Suche in Ihrem Shop durchführt und eine entsprechende Trefferliste anzeigt; dabei dient ein Prozenzeichen (%) als Platzhalter für den Suchtext. Nur wenn eine Such-URL angegeben ist, sehen Besucher bei Ihrem Shop den Button "Treffer im Shop anzeigen".
  4. Speichern Sie Ihre Eingaben.
  5. Im Shopprofil werden im Feld "Schnittstelle" verschiedene Links eingeblendet, mit denen Sie die Schnittstelle testen können. Diese Links werden bei jedem Laden der Profilseite neu erzeugt und sind immer nur eine bestimmte Zeit lang gültig (abhängig davon, wie Sie den request_timeout eingestellt haben).