API-Dokumentation

Laktonaut stellt eine Programmierschnittstelle (API) zur Verfügung, über die fremde Anwendungen Informationen aus der Lebensmitteldatenbank beziehen können.

Derzeit ist nur die Abfrage von Informationen zu einem Artikel mit einer gegebenen GTIN (auch EAN oder "Barcode-Nummer" genannt) möglich.

Die Nutzung der API unterliegt unseren Nutzungsbedingungen (siehe dort insbesondere § 8). Sie bedarf unserer schriftlichen Einwilligung.

Eine gewisse Anzahl von Anfragen zu Testzwecken kann grundsätzlich jeder mit Hilfe des test-Schlüssels (siehe unten) durchführen. Nutzer, die in größerem Umfang auf die API zugreifen möchten, werden gebeten, mit uns Kontakt aufzunehmen und uns ihr Anliegen mitzuteilen. Sie erhalten dann gegebenenfalls einen persönlichen Schlüssel zugeteilt, der eine ausreichende Zahl von Anfragen ermöglicht.

Die folgende Dokumentation richtet sich direkt an Anwendungsentwickler. Vorausgesetzt wird ein prinzipielles Verständnis von HTTP-Anfragen und XML-Daten.

Kapitel

• Anfrage des Clients
• Antwort des Servers
• Beispiel
• Bilder

Um eine Anfrage an den Server zu richten, sendet der Client einen HTTP-GET-Request an www.laktonaut.de auf Port 80 für folgende URL:

Beispiel: http://www.laktonaut.de/api.php?action=query&gtin=4000417025005&key=test

Parameter

gtin

GTIN (EAN) des gesuchten Artikels

Eine gültige GTIN ist ein String aus zumeist 8 oder 13, manchmal auch 12 oder 14 Ziffern. Formal akzeptiert werden allerdings Strings beliebiger Länge. Alle nichtnumerischen Zeichen (beispielsweise Trennzeichen) werden dabei ignoriert. Führende Nullen sind jedoch von Bedeutung – eine GTIN ist ein String und keine Zahl, 0000012345670 also etwas anderes als 12345670.

Die Angabe wird unabhängig von ihrer Länge als vollständige GTIN interpretiert. Eine Suche nach Teil-GTINs ist derzeit nicht möglich.

key

Persönlicher Zugangsschlüssel des Clients; wird auf Anfrage zugeteilt

Zu Testzwecken kann der Schlüssel test verwendet werden. Dieser ist jedoch einer Begrenzung unterworfen, was die Zahl der Anfragen pro IP und Zeiteinheit angeht.

↑ Seitenanfang

Die Antwort des Servers ist vom Client zunächst auf ihren HTTP-Status-Code hin zu prüfen. Der Server verwendet diese Codes semantisch korrekt gemäß RFC 2616.

Bei einem HTTP-Status-Code von 200 (OK) enthält der Body der Antwort ein XML-Dokument (Content-Type: application/xml) nach folgendem Schema:

<?xml version="1.0" encoding="UTF-8"?>
<laktonaut>
    ...
</laktonaut>

Der Zeichensatz für alle Strings ist UTF-8. Die folgenden fünf Zeichen werden, wie in XML üblich, als Entities kodiert:

Bei zukünftigen Änderungen und Erweiterungen der API wird volle Abwärtskompatibilität angestrebt, so dass auch Clients, die die Aktualisierungen noch nicht kennen, weiterhin funktionieren. Dies setzt eine gewisse Flexibilität des Clients voraus; er sollte seinerseits folgende Punkte beachten:

• Die Anordnung von Elementen kann sich ändern, ohne dass dies die Semantik beeinflusst. Es gibt keine starre Reihenfolge.
• Es können neue Elemente hinzukommen. Unbekannte Elemente sind daher nicht als Fehler zu werten, sondern zu ignorieren.
• Elemente können Attribute erhalten. Beispielsweise könnte aus <item> plötzlich <item info="blabla"> werden. Der Client sollte sie trotzdem erkennen.
• Leerzeichen, Tabulatoren usw. sind außerhalb von Texten völlig bedeutungslos und können variieren.

Subelemente von <laktonaut>

status
message
item

Die Subelemente status und message kommen jeweils genau einmal vor. Das Subelement item kann beliebig oft vorkommen, je nach Anzahl der gefundenen Artikel. Die Reihenfolge der Subelemente kann variieren.

status

Statuscode der Antwort als numerischer String (signed integer)

Werte > 1 sind selten und kommen nur in dem Fall vor, dass eine GTIN mehreren unterschiedlichen Artikeln zugeordnet ist.

Der Wert -3 (Fehler: Antwort verweigert) ist meist Folge einer Überschreitung des Abfragelimits, was vor allem unter Verwendung des test-Schlüssels passieren kann.

Falls eine ungültige oder nicht vergebene GTIN übergeben wurde, wird kein Fehlercode zurückgegeben, sondern schlicht 0.

Beispiel: <status>1</status>

message

Vom Menschen lesbare Mitteilung des Servers

Das Element enthält eine Erfolgs- bzw. Fehlermeldung, die rein informativen Zwecken (z. B. für die Fehlersuche) dient und keinesfalls zur automatischen Statusprüfung verwendet werden sollte, da sie variieren kann.

Beispiel: <message>OK: 1 item found</message>

item

Enthält die Daten zu den gefundenen Artikeln

Pro gefundenem Artikel wird genau ein item-Element geliefert, das diesen Artikel beschreibt. Die Anzahl der item-Elemente entspricht also dem Wert der Angabe aus dem status-Element, sofern dieser >= 0 ist. Im Fehlerfall (status < 0) werden keine item-Elemente geliefert.

Subelemente von <item>

id
gtin
name
generic
category
lactose
link
shortlink
timestamp

Alle Subelemente von item kommen in jedem item-Element jeweils genau einmal vor – mit Ausnahme des Subelements category, das mindestens einmal vorkommt. Die Reihenfolge der Subelemente kann variieren.

id

Laktonaut-interne ID des Artikels als numerischer String (unsigned integer)

Beispiel: <id>3928</id>

gtin

GTIN (EAN) des Artikels als String

Die GTIN besteht in der Regel aus 8, 12, 13 oder 14 Ziffern ohne Trennzeichen. Der String ist nicht numerisch zu interpretieren – führende Nullen sind beizubehalten.

Beispiel: <gtin>4000417025005</gtin>

name

Name des Artikels

Beispiel: <name>Ritter Sport Marzipan 100 g</name>

generic

Generische Bezeichnung (Gattungsname) des Artikels

Beispiel: <generic>Schokolade</generic>

category

Name der Kategorie des Artikels

Das category-Element kann auch mehrfach vorkommen, wenn der Artikel in mehrere Kategorien eingeordnet ist.

Beispiel: <category>Süßigkeiten</category>

lactose

Laktosegehalt des Artikels als String

Andere Werte als yes oder no (in genau diesen Schreibweisen) sollten in der aktuellen Version der API nicht vorkommen; falls doch, ist die Angabe als unbekannt zu interpretieren. Keinesfalls sollte etwa jeder Wert != yes als laktosefrei interpretiert werden! Aufgrund der zentralen Bedeutung der Angabe zum Laktosegehalt ist hier ganz besondere Sorgfalt angebracht.

Beispiel: <lactose>no</lactose>

link

Link zur Laktonaut-Beschreibungsseite des Artikels als vollständige URL

Dieser Link ist als Verweis zur Quelle zu verwenden.

Beispiel: <link>http://www.laktonaut.de/laktosefrei-ritter-sport-marzipan-100-g-3928.html</link>

Hinweis: Der Link ist auch dann noch gültig, wenn sich die im Dateinamen enthalten Informationen über Laktosegehalt und Produktnamen inzwischen geändert haben sollten. Wichtig ist allein die ID. Es wird jedoch darum gebeten, die URL nicht zu verändern und nur im Notfall den Kurzlink zu verwenden:

shortlink

Kurzlink zur Laktonaut-Beschreibungsseite des Artikels als vollständige URL

Dieser Kurzlink sollte nur dann als Verweis zur Quelle verwendet werden, wenn Platzgründe dazu zwingen. Der im link-Element angegebene vollständige Link ist wann immer möglich zu bevorzugen.

Beispiel: <link>http://www.laktonaut.de/x3928</link>

timestamp

Zeitpunkt der letzten Änderung des Eintrags als Unix-Timestamp (numerischer String, unsigned integer)

Beispiel: <timestamp>1315990392</timestamp>

↑ Seitenanfang

Anfrage

Antwort

<?xml version="1.0" encoding="UTF-8"?>
<laktonaut>
    <status>1</status>
    <message>OK: 1 item found</message>
    <item>
        <id>3928</id>
        <gtin>4000417025005</gtin>
        <name>Ritter Sport Marzipan 100 g</name>
        <generic>Schokolade</generic>
        <category>Süßigkeiten</category>
        <lactose>no</lactose>
        <link>http://www.laktonaut.de/laktosefrei-ritter-sport-marzipan-100-g-3928.html</link>
        <shortlink>http://www.laktonaut.de/x3928</shortlink>
        <timestamp>1315990392</timestamp>
    </item>
</laktonaut>

↑ Seitenanfang

Mit der Zuweisung eines eigenen Schlüssels erhält der API-Nutzer die Erlaubnis, die folgenden Bilder im Kontext der API-Nutzung zu verwenden. Eine unerlaubte Verwendung ist untersagt.

	Laktonaut-Logo (PNG, 800 x 200, 12 kB)
	Laktonaut-Kuh (PNG, transparent, 333 x 250, 52 kB)
	Symbol "laktosefrei" (PNG, transparent, 30 x 30, 3 kB)
	Symbol "laktosehaltig" (PNG, transparent, 30 x 30, 3 kB)

Wir bitten berechtigte Nutzer darum, die Bilder herunterzuladen und gegebenenfalls in der Größe anzupassen. Eine Direktverlinkung ist nicht erwünscht.

↑ Seitenanfang