API Dokumentation

Die API erlaubt automatisierten Zugriff auf viele Informationen aus unserer Datenbank. Sie versucht sich im Großen und Ganzen an REST-Prinzipien zu orientieren, und verwendet JSON zum Datenaustausch. API Methoden besitzen jeweils eine eigene URL, und Parameter werden via Querystring übergeben.

Zum Zugriff ist ein kostenloser API-Key notwendig. Für mehr Informationen, siehe API-Key.

Für praktische Beispiele der API Nutzung, siehe API-Partner.

Inhalt

Nutzungsbedingungen

  • Die Schnittstelle ist kostenlos für private Nutzung. Ansonsten ist zwar im Zweifelsfall eine Erlaubnis erforderlich, in den allermeisten Fällen ist eine Verwendung im Rahmen einer kommerziellen Webseite aber in Ordnung. Insbesondere das Einblenden von Wertungen im Zusammenhang mit eigenem Inhalt ist explizit gestattet.
  • Wir freuen uns über Backlinks, verpflichtend sind sie aber nicht.
  • Es gibt keine Garantien bezüglich Verfügbarkeit, Uptime oder Geschwindigkeit, der Dienst kann jederzeit eingestellt oder API-Keys deaktiviert werden.
  • Es gibt aktuell keine "harten" Limits bezüglich Anzahl oder Größe der Aufrufe, aber wir bitten darum nicht öfter als nötig anzufragen. Generell empfiehlt es sich die erhaltenen Daten zu cachen: Das verbessert auch die eigene Performance, und macht die Verfügbarkeit unabhängiger von z.B. der Funktion unserer Server.

Schnelleinstieg

>> GET http://critify.de/api/2.0/rest/games/1234?with_reviews=False&apikey="..." >> {"num_reviews": 29, "score": 90, "location": "http:\/\/critify.de\/games\/360\/13\/halo-3\/", "title": "Halo 3"} >> GET http://critify.de/api/2.0/rest/reviews/6000?with_quote=False&apikey="..." >> {"url": "http:\/\/www.cleveland-daily.de\/article/2207", "score": 91, "location": "http:\/\/critify.de\/reviews\/6000\/", "publication": {"id": 52, "repr": "Cleveland Daily"}, "author": {"id": 312, "repr": "Max Fischer"}}

Allgemeines

API-Key

Bis auf test.echo müssen alle Methoden mit einem API Schlüssel aufgerufen werden. Dabei gibt es zwei Möglichkeiten:

Mit dem Query-Parameter apikey lässt sich der Key direkt in die URL einbinden. Dabei ist besonders zu beachten, dass es sich um einen gültigen JSON-String handeln muss, also Anführungszeichen notwendig sind:

>> GET /api/2.0/rest/publications/1?apikey="2fc1666f082c275fb66b1032b6ccbf9a"

Alternativ kann der API-Key auch via HTTP-Header als X-APIKEY mitgeschickt werden.

>> GET http://critify.de/api/2.0/rest/publications/1 .. User-Agent: foo .. Accept-Encoding: bar .. X-ApiKey: 2fc1666f082c275fb66b1032b6ccbf9a

Wie zu sehen ist die JSON-Kodierung in diesem Fall nicht notwendig.

Fehler

Tritt ein Fehler auf, ist die Antwort ein JSON object mit einem Attribut error:

{"error": "Invalid API Key"}

Zusätzlich wird in der Regel ein entsprechender HTTP-Fehlercode gesendet. Im Optimalfall würde man diesen verwenden um den Erfolg eines Aufrufs zu überprüfen, da in extremen Fällen anstelle der JSON-Struktur möglicherweise die Standard Error-500 Seite ausgegeben werden kann.

JSON-Kodierung

JSON wird nicht nur für die Ausgabe verwendet: Auch die eingehenden Parameter müssen korrektes JSON enthalten. Die zwei häufigsten Fehler sind hier string-Argumente die nicht von Anführungszeichen umgeben sind, und bool-Werte, die z.B. als True anstelle dem korrekten true übergeben werden. Dasselbe trifft natürlich auf false zu, sowie auf das Schlüsselwort null.

Auf diese Weise sind mit JSON theoretisch auch komplexere Strukturen möglich:

>> GET /api/2.0/rest/test/echo/[1,true,"string",["a","b"],{"x": 1.4,"y": -1.0}]

Objekt-Referenzen

Eine API-Antwort kann Verweise auf andere Objekte enthalten: Zum Beispiel würde ein Review den jeweiligen Autor referenzieren. In JSON wird ein solcher Verweis von der API als object mit zwei Werten id und repr ausgegeben:

{'author': {'id': 10, 'repr': 'Max Fischer'}, ...}

Während letzteres nützlich ist wenn ohne weiteren Aufwand ein Name zur Anzeige benötigt wird, können über die ID bei Bedarf weitere Informationen nachgeladen werden. Siehe auch unter Mehrere Objekte abfragen.

Eine Ausnahme stellen hier Review-Objekte da, die keine eigene Text-Repräsentation besitzen und lediglich über die ID ausgegeben werden.

Wenn Informationen über eine Ressource abgefragt werden (z.b. die Daten zu einem Review, einer Publikation usw.), dann enthält die Antwort in der Regel ein Attribut location. Es entspricht der URL unter welcher der Inhalt auf critify.de zu finden ist. Die URL ist immer absolut, enthält also auch Protokoll und Domain, und sollte für Backlinks verwendet werden, anstatt die Adresse selbst zusammenzusetzen. Sie ist nicht zu verwechseln mit möglicherweise anderen in der Antwort enthaltenen URLs, die als Metadaten mit der Ressource verknüpft sind (z.B. die Webseite einer Publikation).

Methoden

test.echo

Parameter: data
Aufruf mit: GET, POST
API-Key notwendig: nein

Gibt data exakt so zurück wie erhalten. Hauptsächlich nützlich zu Test- und Debugzwecken.

Beispiele

/api/2.0/rest/test/echo/"hello world"
/api/2.0/rest/test/echo/?data={"foo": "bar"}

games

Parameter: array/int id, [ bool with_reviews, bool with_data, int by_publication ]
Aufruf mit: GET
API-Key notwendig: ja

Gibt das mit id spezifizierte Spiel zurück, oder eine Liste von Spielen, falls id ein JSON-Array ist. Siehe auch → Mehrere Objekte abfragen.

Ist with_data gesetzt, enthält die Ausgabe zusätzliche Infos zum Spiel aus unserer Datenbank (z.B. Publisher).

Mit with_reviews wird ein Array mit den IDs aller Reviews zu diesem Eintrag in die Antwort eingefügt. Fehlt der Parameter oder ist er false, gibt stattdessen das Feld num_reviews zumindest Auskunft über die Anzahl.

Über by_publication können Einträge über Fremd-IDs abgefragt werden, wenn die critify-ID nicht bekannt ist. Mehr Informationen dazu unter → Magazine: Eigene IDs verwenden.
Über den Parameter würde dann die ID des eigenen Magazins bei uns angegeben. Wenn dieser Modus verwendet wird, enthält die Ausgabe die tatsächliche ID des Eintrags in einem Feld id und könnte für zukünftige Anfragen gespeichert werden.
Da es möglich ist, dass eine Fremd-ID in unserer Datenbank mehrfach auftaucht, weil etwa ein Review des Magazins für mehrere Plattform-Versionen eines Spiels veröffentlicht wurde, ist es möglich dass diese Methode bei Verwendung des by_publication Modus eine Liste von Spielen zurückgibt, obwohl nur eine einzelne Fremd-ID abgefragt wurde. In allen anderen Fällen ist garantiert, dass nur dann eine Liste zurückgegeben wird, wenn auch eine Liste von IDs abgefragt wurde. Wird eine Liste von Fremd-IDs abgefragt, kann es so zur Ausgabe einer einfach verschachtelten Liste kommen, wenn ein oder mehrere der Fremd-IDs zu mehreren Spielen auflösen.

Beispiele

/api/2.0/rest/games/1
/api/2.0/rest/games/[1,2]?with_reviews=true

reviews

Parameter: array/int id, [ bool with_quote ]
Aufruf mit: GET
API-Key notwendig: ja

Gibt das mit id spezifizierte Review zurück, oder eine Liste von Reviews, falls id ein JSON-Array ist. Siehe auch → Mehrere Objekte abfragen.

Ein Review-Objekt enthält immer die Felder publication, score, und added_at, wobei letzeres den Zeitpunkt der Eingabe in unsere Datenbank meint. Optional können folgende Daten enthalten sein: author, published_at, url, page und issue.

Ist with_quote gesetzt, wird zudem das zugehörige Zitat ausgegeben.

Die Datumsangaben sind in ISO 8601 kodiert.

Beispiele

/api/2.0/rest/reviews/1
/api/2.0/rest/reviews/[1,2]?with_quote=true

publications

Parameter: array/int id, [ bool with_reviews ]
Aufruf mit: GET
API-Key notwendig: ja

Gibt die mit id spezifizierte Publikation zurück, oder eine Liste von Publikationen, falls id ein JSON-Array ist. Siehe auch → Mehrere Objekte abfragen.

Ein Publication-Objekt enthält die Felder name und location, sowie optional is_print.

Mit with_reviews wird ein Array mit den IDs aller Reviews von dieser Publikation in die Antwort eingefügt. Fehlt der Parameter oder ist er false, gibt stattdessen das Feld num_reviews zumindest Auskunft über die Anzahl.

Beispiele

/api/2.0/rest/publications/1
/api/2.0/rest/publications/[1,2]?with_reviews=true

people

Parameter: array/int id, [ bool with_reviews ]
Aufruf mit: GET
API-Key notwendig: ja

Gibt die mit id spezifizierte Person zurück, oder eine Liste von Personen, falls id ein JSON-Array ist. Siehe auch → Mehrere Objekte abfragen.

Ein Person-Objekt enthält aktuell nur die Felder name und location.

Mit with_reviews wird ein Array mit den IDs aller Reviews von dieser Person in die Antwort eingefügt. Fehlt der Parameter oder ist er false, gibt stattdessen das Feld num_reviews zumindest Auskunft über die Anzahl.

Beispiele

/api/2.0/rest/people/1
/api/2.0/rest/people/[1,2]?with_reviews=true

Unsere seitenweite Suchfunktion implementiert die OpenSearch 1.1 Spezifikation. Das entsprechende OpenSearch Description Document ist zu finden unter:

In der Praxis bedeutet dies, dass den Suchanfragen der optionale Parameter format=rss übergeben werden kann, um die Ergebnisse in einem maschinenlesbarem Format (RSS) abzufragen. Der RSS-Feed enthält ebenfalls die entsprechenden OpenSearch-Metadaten wie z.B. Anzahl der Treffer (als opensearch:totalResults).

Beispiele

/search/?q=singstar&format=rss

Mehrere Objekte abfragen

Wenn die Daten von mehreren Objekten gewünscht sind, etwa alle Reviews eines bestimmten Autors, dann kann es sehr aufwendig sein für jedes einzelne eine neue Anfrage zu starten. Stattdessen macht es Sinn alle auf einmal abzufragen, was von den meisten Methoden der API unterstützt wird. Dazu gibt man statt der ID eines einzelnen Objektes eine (JSON-kodierte) Liste an:

GET http://critify.de/api/2.0/rest/reviews/[1,2,3]

Der obige Aufruf fordert Informationen zu drei Reviews auf einmal an. Der Rückgabe-Wert ist dann kein einzelnes JSON-Objekt mehr, sondern ebenfalls eine Liste von solchen Objekten, mit jeweils demselben Inhalt wie bei einer Einzelanfrage.

Sind eine oder mehrere der IDs ungültig, schlägt nicht gleich der ganze Aufruf fehl: Die entsprechenden Fehler-Objekte werden direkt in die Antwort integriert.

Javascript/JSONP: Beispiele

Die API lässt sich auch direkt im Browser via Javascript/Ajax nutzen. Ein Problem dabei ist allerdings dass die Sicherheitsmodelle der Browser es in der Regel nicht erlauben, dynamisch Daten von anderen Domains nachzuladen. Die API auf critify.de kann auf diesem Wege nur auf critify.de selbst verwendet werden.

Ein gängiger Trick ist es den API-Aufruf durch einen dynamisch erzeugten script-Tag durchführen zu lassen. Die API gibt dann Javascript-Code zurück, der das Ergebnis via einem Funktionsaufruf weitergibt. Da JSON bereits ein Subset von Javascript ist, müssen die Daten nur noch von einem Funktionsaufruf umgeben werden. Die API tut das wenn der Parameter jsonp angegeben ist - er bestimmt die Funktion, die aufgerufen wird:

>> GET /api/2.0/rest/test/echo/[1,2,3]?jsonp=mycallback >> mycallback([1,2,3])

Die gängigen Javascript-Frameworks können sich in der Regel um diese Handarbeit kümmern. Hier zwei Beispiele mit jQuery:

⇒ Beispiel ausführen <span style="color: #6ab825; font-weight: bold">var</span> <span style="color: #d0d0d0">id</span> <span style="color: #d0d0d0">=</span> <span style="color: #d0d0d0">prompt(</span><span style="color: #ed9d13">'ID des gewünschten Spiels:'</span><span style="color: #d0d0d0">);</span> <span style="color: #d0d0d0">jQuery.getJSON(</span><span style="color: #ed9d13">"http://critify.de/api/2.0/rest/games/"</span><span style="color: #d0d0d0">+id,</span> <span style="color: #d0d0d0">{</span> <span style="color: #d0d0d0">jsonp:</span> <span style="color: #ed9d13">'?'</span><span style="color: #d0d0d0">,</span> <span style="color: #d0d0d0">apikey:</span> <span style="color: #ed9d13">"\"demo:be5f257\""</span> <span style="color: #d0d0d0">},</span> <span style="color: #6ab825; font-weight: bold">function</span><span style="color: #d0d0d0">(data)</span> <span style="color: #d0d0d0">{</span> <span style="color: #d0d0d0">jQuery(</span><span style="color: #ed9d13">'#ex1_out'</span><span style="color: #d0d0d0">).</span> <span style="color: #d0d0d0">html(</span><span style="color: #ed9d13">"Score von "</span><span style="color: #d0d0d0">+data.title+</span><span style="color: #ed9d13">": "</span><span style="color: #d0d0d0">+data.score).</span> <span style="color: #d0d0d0">show();</span> <span style="color: #d0d0d0">});</span>

Der folgende Code führt zwei Abfragen durch: Zuerst die IDs der Reviews zum Spiel, und in einem separaten Aufruf die Detailinformationen zu allen Reviews auf einmal.

⇒ Beispiel ausführen <span style="color: #6ab825; font-weight: bold">var</span> <span style="color: #d0d0d0">id</span> <span style="color: #d0d0d0">=</span> <span style="color: #d0d0d0">prompt(</span><span style="color: #ed9d13">'ID des gewünschten Spiels:'</span><span style="color: #d0d0d0">);</span> <span style="color: #d0d0d0">jQuery.getJSON(</span><span style="color: #ed9d13">"http://critify.de/api/2.0/rest/games/"</span><span style="color: #d0d0d0">+id,</span> <span style="color: #d0d0d0">{</span> <span style="color: #d0d0d0">jsonp:</span> <span style="color: #ed9d13">'?'</span><span style="color: #d0d0d0">,</span> <span style="color: #d0d0d0">apikey:</span> <span style="color: #ed9d13">"\"demo:be5f257\""</span> <span style="color: #d0d0d0">},</span> <span style="color: #6ab825; font-weight: bold">function</span><span style="color: #d0d0d0">(data)</span> <span style="color: #d0d0d0">{</span> <span style="color: #d0d0d0">jQuery(</span><span style="color: #ed9d13">'#ex1_out'</span><span style="color: #d0d0d0">).</span> <span style="color: #d0d0d0">html(</span><span style="color: #ed9d13">"Score von "</span><span style="color: #d0d0d0">+data.title+</span><span style="color: #ed9d13">": "</span><span style="color: #d0d0d0">+data.score).</span> <span style="color: #d0d0d0">show();</span> <span style="color: #d0d0d0">});</span>

Magazine: Eigene IDs verwenden

Daten lassen sich normalerweise nur abfragen wenn die entsprechende ID in unserer Datenbank bekannt ist. Diese für viele Einträge ausfindig zu machen kann eine Menge Arbeit sein.
Online-Magazine, die unsere Wertungen einblenden möchten und von uns geführt werden, können in der Regel stattdessen ihre eigenen IDs zu verwenden.

Möglich macht das die Tatsache, dass wir zu allen Reviews eine Quell-URL gespeichert haben. Sofern dort Informationen enthalten sind über die das besprochene Spiel eindeutig identifizierbar ist, können wir auf unserer Seite die fremde ID einem unserer eigenen Spiel-Datensätze zuordnen. Dieser Ansatz hat sehr bequem, hat allerdings auch einige Einschränkungen:

  • Er funktioniert nur für Einträge, zu denen das Magazin ein eigenes Review veröffentlicht hat.
  • Das jeweilige Review muss sich in unsere Datenbank befinden. Das betrifft in erster Linie Archivdaten, die bei uns größtenteils noch fehlen, und bei neuen Artikeln gibt es natürlich die Verzögerung, bis der Eintrag bei uns übernommen ist.

Da wir auf unserer Seite erst dafür sorgen müssen dass die korrekte Fremd-ID aus den URLs ausgelesen wird, bitten wir bei Interesse an dieser Funktion um einen kurzen Hinweis.

Zum Schluss

Die Daten auf die über die API zugegriffen werden kann sind aktuell noch beschränkt. In der Zukunft würden wir dies gerne je nach Bedarf erweitern. Wer Erweiterungen benötigt oder sonstige Wünsche oder Fragen hat, kann sich jederzeit an uns wenden.

Alle vergangenen und zukünftigen Änderungen sind im Changelog zu finden. Bei größeren Updates, die möglicherweise zu Inkompatibilitäten oder Fehlern führen könnten, werden wir API-Key Besitzer per E-Mail benachrichtigen.

Changelog

29. März 2009

  • Da Fremd-IDs in unserer Datenbank nun auch offiziell mehrfach auftauchen dürfen (beispielsweise könnte sich die Fremd-ID auf ein Review beziehen, das für mehrere Plattform-Versionen eines Spiels veröffentlicht wurde), hat sich die Funktionsweise der games-Methode in diesen Fällen leicht geändert: Es wird dann eine Liste alle Spiele zurückgegeben, auf die die Fremd-ID passt, auch wenn nur eine einzelne ID abgefragt wurde. Zuvor war garantiert, dass bei einer Einzelabfrage auch immer nur ein Objekt zurückgegeben wird. Dies betrifft auch die alte Version 1.0 der API.

09. Februar 2009

  • Minimale Korrekturen.

14. September 2008

23. Februar 2008

  • Fix: publications akzeptierte keine Argumente.
  • Fix: Bei Fehlern wurde nicht der korrekte HTTP-Fehlercode verwendet.
  • Neu: games gibt nun die tatsächliche ID zurück, wenn es mit by_publication aufgerufen wird.

22. Februar 2008

  • Problem behoben dass teilweise die API-Fehler versteckt hatte.

20. Februar 2008

Erste öffentliche Version (2.0)

Dezember 2007

Eingeschränkte Testversion (1.0)