Bilder Upload ∗ API

Grundlagen

Der Bilder Upload stellt eine REST-ähnliche, XML-basierende API zur Verfügung, mit der andere Dienste oder Programme auf die Bilder zugreifen oder neue Bilder hochladen können.
Dieses Dokument enthält eine Beschreibung der API-Befehle und Beispiele für ihre Nutzung.

Alle API-Befehle werden über folgende URL ausgeführt:

http://img.i7m.de/api/[befehl]

Die Daten aller Anfragen müssen per HTTP POST gesendet werden, die Parameter werden dabei application/x-www-form-urlencoded übertragen.

Alle Daten müssen als Zeichensatz mit UTF-8 gesendet werden!

Antwort

Jede Antwort enthält auf äußerster Ebene das rsp-Tag, dessen state-Attribut beschreibt, ob eine Anfrage erfolgreich war. Der HTTP-Status-Code ist unabhängig davon immer 200, andernfalls muss angenommen werden, dass die Antwort undefiniert ist!

Die Erfolgsantworten sind bei den einzelnen Befehlen aufgeführt. Tritt ein Fehler auf sieht die Antwort z.B. so aus:

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="fail">
	<error code="105" msg="Unbekannte Methode" />
</rsp>

Fehlercodes

-1Unbekannter Fehler
100Dienst nicht verfügbar
101Authentifizierung benötigt
102Benutzername oder Password falsch
103Bild konnte nicht gespeichert werden
104Dateiformat nicht akzeptiert
105Unbekannte Methode
106Fehlerhafter Methodenaufruf
107Bild nicht vorhanden
108Nicht vorhanden
109Ja
110Nein
111Sicherheitsverletzung
112Interner Fehler
113Unbekannter API-Schlüssel
114Der Client hat eine zu alte Version
115Angabe eines API-Keys erforderlich

API Keys

Du hast die Möglichkeit bei jeder Anfrage auch einen API-Key mitzusenden um deinen Client zu identifizieren.
So kann ich zum einen genauere Statistiken anlegen :-) und du kannst z.B. auch sehr leicht eine Update-Prüfung in deinen Client einbauen.

Der API-Key ist momentan optional, wird aber später Pflicht werden.

Du kannst deine API-Keys selber verwalten. Jede Programmversion erhält dabei einen eigenen, zufällig generierten API-Key. Um diese Keys verwalten zu können, musst du deinen Account dafür von einem Administrator freischalten lassen.

Im Zusammenhang mit API-Keys können die Fehler 113–115 auftreten.

Parameter:
api_key(optional) Der API-Key

Befehle

image.thumb
image.thumbset
image.latest

image.upload
image.delete
user.images
user.stats
user.login
user.sets

set.add
set.exists
set.images

info.anonymous

image.thumb

Gibt die URL eines Thumbnailbildes für ein angegebenes Bild an.

<url href="http://img.i7m.de/thumbs/1234_bild.jpg" imageid="1234_bild.jpg" />
Parameter:
imageid(erforderlich) ID des Bildes

image.thumbset

Wie image.thumb, allerdings können gleichzeitig mehrere Bilder angefragt werden.

Parameter:
imageid(erforderlich) ID des Bildes. Mehrfachverwendung möglich.
thumbdata(optional) Entweder inline, attach oder none (Standard).
Beispiel:
<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
      (<ref imageid="foo">
              (<url href="http://img.i7m.de/thumbs/foo" />
              |<error code="107" msg="Bild nicht vorhanden"/>)
              (<data encoding="base64">[…]</data>
              |<attachment href="cid:[…]" />)?
        </ref>)+
</rsp>

( )+ Für jede (eindeutige) imageid wird jeweils ein ref-Tag zurückgegeben. Die Reihenfolge der Einträge ist zufällig.
( | ) enthält entweder ein url-Tag mit einem Verweis zum Vorschaubild, oder wenn bei einer imageid ein Fehler auftritt, ein error-Tag mit der Fehlerbeschreibung (siehe Abschnitt Antwort).

Der thumbdata-Parameter

Mit dem thumbdata-Parameter können die Thumbnail-Bilder direkt als Teil der Antwort geliefert werden und der Client erspart sich zusätzliche HTTP-Anfragen.

Grundsätzlich gilt: Dieser Parameter wird vom Server nach dem Best-Effort-Prinzip bearbeitet, d.h. es gibt keine Garantie, dass die Antwort tatsächlich alle oder überhaupt einen Teil der Thumbnail-Bilder enthält.
Der Client muss überprüfen, für welche angefragten Bilder tatsächlich ein Thumbnail geliefert wurde und ggf. fehlende Thumbnails mit der empfangenen URL manuell nachladen.

Der Parameter ( | )? unterstützt zwei Modi:
Im inline-Modus werden die Daten direkt in das XML-Dokument eingefügt. Dazu wird das data-Tag verwendet, welches die Binärdaten Base64-codiert (RFC 2045) enthält.
Dagegen wird im attach-Modus eine multipart/related-Nachricht (RFC 2387) zurückgeliefert, die aus der XML-Antwort und den Dateien als Anhang besteht. Mit Hilfe der Content-ID (RFC 2045), die als cid:-URL (RFC 2392) im attachment-Tag der XML-Antwort und als MIME-Header in den Attachments definiert ist, wird die Verknüpfung hergestellt.

Achtung: Ein Client, der den attach-Modus verwenden will, muss gleichzeitig mit Transfer-Encoding: Chunked (HTTP/1.1) und multipart/related-Nachrichten (oder mindestens multipart/mixed) umgehen können.

Beispiel:

Im folgenden Beispiel wurden die vier Bilder 1234_Bild, notfound, foobar und abcdef angefragt. Das Bild notfound wurde nicht gefunden und die Antwort enthält eine Fehlermeldung. Das Bild foobar wurde zwar gefunden, allerdings wurde kein Anhang mitgeliefert - hier muss der Client das Thumbnail einzeln anfragen. Die Beiden Bilder 1234_Bild und abcdef wurden schließlich jeweils mit angehängtem Thumbnail zurückgeliefert, welches über den attachment-Tag referenziert wird.

HTTP/1.1 200 OK
Content-Type: multipart/related;boundary="ABC123DEF";
    type="application/xml";start="<XYZ456789.start@img.i7m.de>"


--ABC123DEF
Content-Type: application/xml;Charset=UTF-8
Content-ID: <XYZ456789.start@img.i7m.de>

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
    <ref imageid="1234_Bild">
        <url href="http://img.i7m.de/thumbs/1234_Bild" />
        <attachment href="cid:thumb-250-scaled-1234_Bild@img.i7m.de" />
    </ref>
    <ref imageid="notfound">
        <error code="107" msg="Bild nicht vorhanden" />
    </ref>
    <ref imageid="foobar">
        <url href="http://img.i7m.de/thumbs/foobar" />
    </ref>
    <ref imageid="abcdef">
        <url href="http://img.i7m.de/thumbs/abcdef" />
        <attachment href="cid:thumb-250-scaled-abcdef@img.i7m.de" />
    </ref>
</rsp>
--ABC123DEF
Content-Disposition: attachment;filename="1234_Bild"
Content-Length: 5678
Content-Type: image/jpeg
Content-ID: <thumb-250-scaled-1234_Bild@img.i7m.de>

[Bild 1]
--ABC123DEF
Content-Disposition: attachment;filename="abcdef"
Content-Length: 1234
Content-Type: image/jpeg
Content-ID: <thumb-250-scaled-abcdef@img.i7m.de>

[Bild 2]
--ABC123DEF--

image.latest

Liefert die URL zu den 5 neusten Bildern.
Datumsangaben sind RFC2822 formatiert

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<image>
		<imageid>1234_bild.jpg</imageid>
		<description>Ein Bild</description>
		<url href="http://img.i7m.de/show/1234_bild.jpg" />
		<uploadedat>Fri, 12 Jan 2007 16:01:07 +0200</uploadedat>
		<uploadedby>user1</uploadedby>
	</image>
	<image>
		<imageid>1328_foo.jpg</imageid>
		<url href="http://img.i7m.de/show/1234_bild.jpg" />
		<uploadedat>Sun, 07 Jan 2007 15:12:10 +0200</uploadedat>
	</image>
	[…]
</rsp>
Parameter:
count(optional) Anzahl der Bilder

image.upload

Mit der image.upload Funktion können Bilder hochgeladen werden (anonym oder mit Anmeldung)
Im Erfolgsfall wird die URL zum Bild und die ID zurückgegeben:

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<url href="http://img.i7m.de/show/1234_bild.jpg" imageid="1234_bild.jpg" />
</rsp>
Parameter:
image(erforderlich) Das Bild (binär)
filename(erforderlich) Der Dateiname des Bildes
desc(optional) Eine Bildbeschreibung
hidden(optional) 0 oder 1 für versteckt
brand(optional) 0 oder 1 für Bild branden
username(optional) Benutzername
password(optional) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)
set(optional) Nur bei angemeldeten Benutzern - Der Name des Sets, in dass das Bild aufgenommen werden soll
Achtung! Eine Upload-Anfrage unterscheidet sich von anderen Anfragen (es muss als Content-type multipart/form-data verwendet werden, Zeilenumbrüche werden nach dem Schema CRLF gemacht)
Beispiel:
POST /api/image.upload HTTP/1.1
Content-Type: multipart/form-data; boundary=ABC123DEF
Host: img.i7m.de
Content-Length: 1234

--ABC123DEF
Content-Disposition: form-data; name="desc"

Das ist ein Testbild
--ABC123DEF
Content-Disposition: form-data; name="hidden"

0
--ABC123DEF
Content-Disposition: form-data; name="username"

user1
--ABC123DEF
Content-Disposition: form-data; name="password"

$55095a1a0ef6fa8b8ff4d78646d58a7f
--ABC123DEF
Content-Disposition: form-data; name="image"; filename="test.jpg"
Content-Type: image/jpeg

[Bild]
--ABC123DEF--
			

image.delete

Funktion um ein Bild zu löschen.
Im Erfolgsfall wird success zurückgegeben:

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<success />
</rsp>
Parameter:
imageid(erforderlich) Die ID des Bildes
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)

user.stats

Liefert statistische Angaben zum Benutzer:
Anzahl der Bilder,Speichernutzung (in Byte)

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<imagecount>12</imagecount>
	<fsusage>210432532</fsusage>
</rsp>
Parameter:
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)

user.images

Liefert alle Bilder eines Benutzers

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<image>
		<imageid>1234_bild.jpg</imageid>
		<description>Ein Bild</description>
		<url href="http://img.i7m.de/show/1234_bild.jpg" />
		<uploadedat>Fri, 12 Jan 2007 16:01:07 +0200</uploadedat>
		<hidden>1</hidden>
	</image>
	<image>
		<imageid>1328_foo.jpg</imageid>
		<url href="http://img.i7m.de/show/1234_bild.jpg" />
		<uploadedat>Sun, 07 Jan 2007 15:12:10 +0200</uploadedat>
		<hidden>0</hidden>
	</image>
	[…]
</rsp>
Parameter:
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)
count(optional) Maximale Anzahl an Bildern, die zurückgeliefert werden soll.
offset(optional) Anzahl an Bildern (am Anfang), die übersprungen werden sollen (0 = Ausgabe ab 1. Bild)

user.login

Dient zur Prüfung des Benutzernamens/Passwort bei API-Clients. Liefert Code 101 bei Fehler, sonst:

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<success />
</rsp>
Parameter:
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)

user.sets

Eine Liste aller Sets für den angegebenen Benutzer holen

Parameter:
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)

Das Ergebnis besteht aus einer Liste von set-Tags, die als Inhalt den Namen des Sets und zusätzlich als Attribut title den Titel des Sets enthalten. Hat der Benutzer noch keine Sets angelegt, ist der rsp-Tag leer.

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<set title="Set mit Fotos">set-mit-fotos</set>
	<set title="Mein Urlaub 2009">mein-urlaub-2009</set>
</rsp>

set.add

Legt ein neues Set für einen Benutzer an

Parameter:
username(erforderlich) Benutzername
password(erforderlich) Password (Klartext-Passwörter müssen mit _ prefixt werden und md5-verschlüsselte mit $)
title(erforderlich) Der Titel des Sets
description(optional) Eine Beschreibung des Sets

Im Erfolgsfall wird der Name des Sets (Bitte nicht mit Titel gleichsetzen) zurückgegeben

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<set>mein-neues-set</set>
</rsp>

set.exists

Prüft, ob das angegebene Set vorhanden ist

Parameter:
user(erforderlich) Name des Benutzers, dem das Set gehört
set(optional) Der Name (= ID!) des Sets
title(optional) Wenn der genaue Name des Sets nicht bekannt ist kann der Name über den Titel gesucht werden

Es muss entweder set ODER title als zusätzlicher Parameter angegeben werden.
Das Ergebnis bei set ist ein einzelner Tag yes oder no.
Das Ergebnis bei title ist entweder ein Tag no oder im Erfolgsfall ein Tag set, dessen Inhalt der Name des Sets ist.
Gibt es den angegeben Benutzer nicht, tritt Fehler 108 auf!

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<yes />
</rsp>

set.images

Liefert alle oder einen Teil der Bilder in einem Set.
Die Reihenfolge der Elemente ist aufsteigend (ältestes Bild zuerst).

Fehler:

Wenn Benutzer oder Set nicht gefunden werden tritt Fehler 108 auf.

Parameter:
user(erforderlich) Name des Benutzers, dem das Set gehört.
set(erfoderlich) Der Name des Sets (nicht verwechseln mit dem Titel).
count(optional) Maximale Anzahl an Bildern, die zurückgeliefert werden soll (Standard: Alle).
offset(optional) Anzahl an Bildern (am Anfang), die übersprungen werden sollen (0 = Ausgabe ab dem 1. Bild)
Beispiel:
<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
      (<image>
                <imageid>example</imageid>
                <url href="http://img.i7m.de/s/example"/>
              (<description>Ein Beispielbild</description>)?
                <uploadedat>Sun, 21 Jun 2009 21:49:46 +0200</uploadedat>
              (<uploadedby>admin</uploadedby>)?
              (<hidden>1</hidden>)?
        </image>)*
</rsp>

( )* Ein leeres Set wird eine leere rsp-Antwort zurückliefern, andernfalls entsprechend ein image pro Eintrag.
( )? Die Tags description, uploadedby und hidden sind optional und nicht zwangsweise bei jedem Bild vorhanden.

info.anonymous

Gibt an, ob derzeit ein anonymer Upload gestattet ist

<?xml version="1.0" encoding="utf-8" ?>
<rsp state="ok">
	<yes />
</rsp>

Gibt yes oder no zurück.