Zu Handbuch Javascript-API

Installation und Einbindung der Javascript-API

Um mit der Javascript-API auf die Webservices von Golem.de zuzugreifen, müssen Sie mit dem <script>-Tag die erforderlichen Javascript-Dateien einbinden. Dazu muss im src-Attribut des Tags die jeweilige Adresse der einzubindenen Javascript-Bibliothek angegeben werden. Dazu gibt es zwei Möglichkeiten:

  1. Sie binden die erforderlichen Javascript-Dateien direkt von api.golem.de ein.
  2. Sie laden die benötigten Javascript-Dateien herunter und platzieren die Dateien an einem Ort ihrer Wahl. Und binden die Dateien von diesem Ort ein.

Wie die Javascript-Dateien benannt und platziert sind

Die Javascript-API besteht aus einer Reihe von Packages. Jedes Package umfasst eine oder mehrere Klassen und die zugehörigen Unterklassen. Jede Klasse mit ihren Unterklassen befindet sich in einer eigenen Datei. Sie können vom Namen des Packages und der Klasse auf ihren Pfad und den Dateinamen schließen. Eine Ausnahme bildet lediglich das Core-Package.

Derzeit existieren folgende Packages:

  • Core – Dieses Basis-Package umfasst grundlegende Funktionen, die von anderen Packages benutzt werden. Sie benötigen es jedesmal, wenn Sie Golem.de-API benutzten wollen.
  • Golem.Api.Article – Das Article-Package umfasst Klassen zum Zugriff auf Artikeldaten, Artikellisten und die Artikelsuche.
  • Golem.Api.Video – Das Video-Package umfasst Klassen zum Zugriff auf Videodaten, Videolisten und die Videosuche.

Wenn Sie eine bestimmte Klasse einbinden wollen, dann ersetzen Sie einfach alle Punkte im Klassennamen durch Schrägstriche. So erhalten Sie ihren Pfad und den Dateinamen, der noch durch die Dateiendung .js ergänzt wird.

Beispiele: Die Klasse Golem.Request befindet sich im Verzeichnis Golem in der Datei Request.js. Die Klasse Golem.Api.Article.Top befindet sich im Verzeichnis Golem/Api/Article in der Datei Top.js.

Konkret könnte die Einbindung der Klasse Golem.Api.Article.Top also wie folgt aussehen:

<!-- Diese beiden Dateien sind stets erforderlich! -->
<script type="text/javascript" src="Golem/Request.js"></script>
<script type="text/javascript" src="Golem/Api.js"></script>

<!-- Diese Datei enthält die gewünschte Klasse -->
<script type="text/javascript" src="Golem/Api/Article/Top.js"></script>
Beispiel 1: Einbindung der Klasse Golem.Api.Article.Top

Minified-Dateien

Von jeder dieser Dateien gibt es auch eine sogenannte Minified-Datei. Diese Version der Datei unterscheidet sich nicht funktionial. Es wurden lediglich unnötige Kommentare sowie nicht erforderliche Zeilenumbrüche und Leerzeichen entfernt. Dadurch sind diese Dateiversion deutlich kleiner. Das wirkt sich positiv auf die Geschwindigkeit aus, mit der die Datei heruntergeladen und ausgeführt wird.

An den Namen der Minified-Versionen der Dateien wird ein -min angehängt. Zum Beispiel: Die Minified-Version der Datei Request.js heißt Request-min.js, die von Top.js heißt Top-min.js

Sie sollten möglichst die Minified-Versionen der Dateien einsetzen. Nur wenn Sie einen Fehler in der API vermuten und entsprechende Werkzeuge zur Fehlersuche einsetzen, sollten Sie darauf verzichten.

Package-Dateien

Wenn Sie nicht nur eine einzelne Klasse innerhalb einer Seite benötigen, müssen Sie nicht jede einzeln einbinden. Stattdessen können Sie die jeweiligen Package-Datei benutzen. Jede Package-Datei enthält alle Klassen eines Packages in einer einzelnen Datei:

  • Golem/Core.js umfasst die Dateien Golem/Request.js und Golem/Api.js.
  • Golem/Api/Article-full.js umfasst alle Dateien des Packages Golem.Api.Article.
  • Golem/Api/Video-full.js umfasst alle Dateien des Packages Golem.Api.Video.

Auch von diesen Dateien existieren korrespondierende Minified-Versionen.

Wenn Sie die Javascript-API in Ihrer Seite nutzen, müssen Sie stets die Dateien des Core-Packages als erstes einbinden, wie im obigen Beispiel zu sehen.

Statt jede einzelne Datei einzubinden, nutzen Sie einfach die Minified-Version der Core-Package-Datei Golem/Core-min.js. Das reduziert die Dauer des Downloads Ihrer Webseite.

<!-- Binde Core-Package ein! -->
<script type="text/javascript" src="Golem/Core-min.js"></script>

<!-- Binde das Article-Package in der Minified-Variante ein -->
<script type="text/javascript" src="Golem/Api/Article-full-min.js"></script>
Beispiel 2: Einbindung des Article-Packages

URLs der Javascript-Dateien auf api.golem.de

Für die Adressierung der Javascript-Dateien gelten die oben genannten Regeln zur Pfad- und Dateinamenbildung. Die Basis-URL für die Dateien ist

Für Versionsnummer setzen Sie die gewünschte Versionsnummer der Javascript-API ein.

Die aktuelle Version der Javascript-API erreichen Sie stets unter

Beachten Sie allerdings, dass es bei Versionsänderungen zu Änderungen an der API kommen kann. Dadurch könnte Ihr eigener Code nicht mehr funktionieren. Sie sollten auf die Latest-Version nur während der Entwicklungsphase verweisen und später eine konkrete Version der API einbinden.

An die Basis-URL wird dann der Pfad und der Dateiname der gewünschten Javascript-Datei angehangen:

<!-- Binde Core-Package ein! -->
<script type="text/javascript"
 src="http://api.golem.de/download/js/latest/Golem/Core-min.js"></script>

<!-- Binde das Article-Package in der Minified-Variante ein -->
<script type="text/javascript"
 src="http://api.golem.de/download/js/latest/Golem/Api/Article-full-min.js"></script>
Beispiel 3: Einbindung des Article-Packages von api.golem.de

Download und Installation der Javascript-Dateien

Alle Dateien der Javascript-API, die API-Referenz, Beispiele und Unittest können Sie in einem Paket herunterladen. Der Dateiname ist stets Golem_Javascript.zip. Die aktuelle Version des Paketes erhalten sie unter http://api.golem.de/download/js/latest/Golem_Javascript.zip.

Möchten Sie eine bestimmte Version herunterladen, so gehen Sie auf http://api.golem.de/download/. Dort erhalten Sie eine Liste der verfügbaren Versionen.

Entpacken Sie die Datei in ein beliebiges Verzeichnis. Nach dem Entpacken finden Sie vier Verzeichnisse vor:

  • doc enthält die API-Referenz.
  • examples enthält für jede Klasse ein funktionsfähiges Beispiel. Bevor Sie die Beispiele ausprobieren können, müssen Sie in der jeweiligen Datei noch ihren Entwicklerschlüssel eintragen.
  • Golem enthält die Javascript-Dateien der API.
  • tests enthält die Unit-Tests für jede Klasse der Javascript-API.

Um die API zu nutzen, benötigen Sie lediglich das Verzeichnis Golem. Kopieren Sie es an eine gewünschte Position in Ihrem Web-Root. Weitere Installationsschritte sind nicht erforderlich.

Die Beispiele ausprobieren

Um die Beispiele im Verzeichnis Examples ausprobieren zu können, muss lediglich der Entwicklerschlüssel eingetragen werden. Suchen Sie dazu in der jeweiligen Datei die Zeile

 Golem.Request.KEY = ''; // your developer key goes here

Fügen Sie den Entwicklerschlüssel zwischen die Anführungszeichen ein. Danach können Sie die jeweilige Datei mit Ihrem Browser aufrufen. Die Position der Datei spielt keine Rolle, da alle weiteren erforderlichen Dateien direkt von api.golem.de geladen werden.



Zu Handbuch Javascript-API