dropme.de Zur Blog-Übersicht

Api Dokumentation

Last updated at Mon 19.12.2012, 10:43, by Max

Table of Contents

Die Nutzung des API unterliegt den Nutzungsbedingungen.

Aufruf ⇑ top

Alle API-Methoden werden per HTTP-POST aufgerufen und geben ihr Ergebnis JSON-codiert zurück. Der Host ist dropme.de. Alle Parameter müssen mit UTF-8 codiert sein.

Authentifizierung ⇑ top

Die Verwendung des API erfordert einen gültigen Benutzeraccount und einen API-Schlüssel. Die Authentifizierung kann entweder direkt oder per OAuth erfolgen.

[deprecated] Bei der direkten Methode werden bei jedem Aufruf die POST-Parameter key, username und password mitgesendet. Diese Parameter sind immer zusätzlich zu den unten angegebenen funktionsspezifischen Parametern zu übergeben. Die direkte Authentifizierung erfolgt über unverschlüsseltes HTTP, ist somit sehr unsicher und nicht zu empfehlen.

[recommended] Bei der Authentifizierung mit OAuth wird der Benutzer zunächst auf einen Dialog weitergeleitet, auf dem er der App die benötigten Berechtigungen erteilen kann. Anschließend erhält die Anwendung einen Code, mit dem sie einen access_token abrufen kann.

Weitere Informationen zu diesem Verfahren kannst du dem Beispiel mit PHP und dem Beispiel mit JavaScript entnehmen.

Ein API-Schlüssel kann für den nicht-kommerziellen Gebrauch kostenlos angefordert werden. Wenn Sie das Drop Me.de-API kommerziell nutzen möchten, kontakieren Sie uns.

Test ⇑ top

Zum Testen der Funktionen kann das Kommandozeilenprogramm curl verwendet werden.

Beispielaufruf:
curl -d "key=MeinAPISchluessel" -d "username=MeinBenutzer" -d "password=MeinPasswort" "http://dropme.de/api/clipboards/user/mw"


/api/clipboards/last ⇑ top

Ruft die Liste der zuletzt vom Nutzer verwendeten Clipboards ab.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"last_used" :
[ clipboard1, ..., clipboardn ]
}


/api/clipboards/user/<Username>  ⇑ top

Ruft die Liste der geschützen, sichtbaren Clipboards des angegebenen Benutzers ab.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"username" : "<Username>",
"last_used" :
[ clipboard1, ..., clipboardn ]
}


/api/clipboards/favtag/<Tag>  ⇑ top

Ruft die Liste der Clipboards ab, die der angemeldete Benutzer unter dem angegebenen Tag zu seinen Favoriten hinzugefügt hat.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"list" :
[ clipboard1, ..., clipboardn ]
}


/api/items  ⇑ top

Ruft die "Zeitleiste" für den eingeloggten Benutzer ab. Dabei werden die Dateien des Benutzers selbst, seiner Freunde und in seinen Clipboards berücksichtigt (sortiert nach Datum).

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"item_list" :
[ item1, ..., itemn ]
}


/api/items/<Clipboard-ID> ⇑ top

Ruft Informationen und enthaltene Dateien des angegebenen Clipboards ab.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"cbid" : <Integer>,        // Eindeutige Clipboard-ID
"name" : "<String>",       // URL-Name des Clipboards
"exists" : <Boolean>,      // existiert das Clipboard? --> immer true
"cblink" : "<URL>",        // Absolute URL des Clipboards
"state" : <Integer>,       // 1 = Privat 2 = Geschützt 3 = Öffentlich
"s_comments" : <Boolean>,  // Kommentare erlaubt?
"s_editall" : <Boolean>,   // Eingeladene Benutzer dürfen auch fremde Dateien bearbeiten/löschen?
"s_notemp" : <Boolean>,    // Einladungen nicht temporär annehmbar?
"s_listable" : <Boolean>,  // in Clipboard-Listen und Suchergebnissen sichtbar?
"icon" : "<URL>",          // Icon-URL
"description" : "<String>",// Langer Name des Clipboards
"owner" : "<String>",      // Benutzername des Besitzers
"can_upload" : <Boolean>,  // Rechte zum Uploaden vorhanden
"can_admin" : <Boolean>,   // Rechte zum Administrieren vorhanden
"clipDesc_mode" : 0,       // reserviert
"user" : "<String>",       // Benutzername des eingeloggten Nutzers
"item_list" : [ item1, ..., itemn ] // Liste aller enthaltenen Dateien
}


/api/favtags/ ⇑ top

Gibt die Liste aller von diesem Benutzer für Favoriten verwendeten Tags zurück.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"list" : ["tag1", "tag2", "tagn"]
}


/api/favtag/<Clipboard-ID>/-<Tag> ⇑ top

Setzt oder löscht den Favorit mit dem angegebenen Tag auf das angegebene Clipboard.

Vordefinierte Tags (System):
fav         : normaler Favorit
follow      : in Newsfeed einbeziehen


Apps können beliebige Tags verwenden, die mit "my" beginnen sollten. Diese können hier eingetragen (reserviert) werden:
myimgchat   : Bookmark in http://htmldesktop.net/imagechat/
mybml       : Bookmark in http://htmldesktop.net/dropme_bookmarklet/


Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true
}


/api/friends ⇑ top

Ruft die Liste der Freunde des eingeloggten Benutzers ab.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"friends" :
[ friend1, ..., friendn ]
}


/api/read/<Item-ID> ⇑ top

Gibt Informationen zur Datei mit der angegebenen Item-ID zurück.

Zusätzliche POST-Parameter:
keine

Rückgabe:
{
"success" : true,
"clip" : item,
"data_url" : "<String>",       // Direkt-URL zur Datei
"self_url" : "<String>",       // URL zur Beschreibungsseite
"filetype_desc" : "<String>",  // Dateityp (Deutsch)
"editable" : <Boolean>,        // Bearbeiten erlaubt?
"cb" : clipboard,
"cbname" : "<String>",         // Name des Clipboards
"user" : "<String>"            // Name des eingeloggten Benutzers
}


/api/write/<Clipboard-ID> ⇑ top

Lädt eine Datei in das angegebene Clipboard hoch.

Zusätzliche POST-Parameter:
Der POST muss als multipart/form-data gesendet werden. Im Feld uploaded muss die zu speichernde Datei übergeben werden (HTTP-Upload, wie <input type=file>). Der angegebene filename wird als Dateiname verwendet.

Beispiel:
[...]
Content-Type: multipart/form-data; boundary=TRENNZEICHEN
 
--TRENNZEICHEN
Content-Disposition: form-data; name="username"
 
MeinBenutzername
--TRENNZEICHEN
Content-Disposition: form-data; name=password"
 
MeinPasswort
--TRENNZEICHEN
Content-Disposition: form-data; name="uploaded"; filename="Dateiname.png"
Content-Type: image/png
 
?PNG [...]
--TRENNZEICHEN--


Rückgabe:
{
"success" : true,
"friends" :
[ friend1, ..., friendn ]
}


/api/delete/<Item-ID> ⇑ top

Löscht das angegebene Item.

Zusätzliche POST-Parameter:
delete=yes

Rückgabe:
{
"success" : true
}


/api/create  ⇑ top

Erstellt ein neues Clipboard.

Zusätzliche POST-Parameter:
state=<Int>&name=<String>&desc=<String>


Mögliche Werte für state:
STATE_PRIVATE = 1
STATE_PROTECTED = 2
STATE_PUBLIC = 3


Rückgabe:
{
"success" : true,
"created" => "<Boolean>",  // neu angelegt? (sonst schon vorhanden)
"cbid" => <Int>,           // Clipboard-ID
"url" => "<String>"        // URL des Clipboards
}


/item/preview_image/<Item-ID>/<Size>  ⇑ top

Gibt ein Vorschaubild es Eintrags im JPG-Format aus. Erlaubte Bildgrößen sind 64, 256, 400, 512, 800 Pixel.

Beispiel:

http://dropme.de/item/preview_image/1550/64
http://dropme.de/item/preview_image/1550/64

http://dropme.de/item/preview_image/1550/400Gibt
http://dropme.de/item/preview_image/1550/400

Verwendete Objekt-Typen: ⇑ top

 friend => {
   "username" : "<String>" , "fullname" : "<String>"
 }


 item => {
 }


 clipboard => {
 }


Fehlermeldungen: ⇑ top

Im Falle eines Fehlers wird ein JSON-Objekt mit den Eigenschaften success, code und error zurückgegeben sowie ein entsprechender HTTP-Status-Code gesetzt.

Beispiel:

Rückgabe:
{
"success" : false,
"code" : 404,
"error" : "clipboard not found"
}


Statuscode:
"HTTP/1.1 404 Not Found"



Categories: This article is not in any categories