API

Information

Die Interdose ShortURL API ermöglicht von Programmen und Web-Services aus Kurz-URLs auf piep.net zu erzeugen.

Grundlagen

Die API ist über die folgende Adresse zu erreichen:

http://api.piep.net/api/shorturl/v1/shorten

Parameter können wahlweise mittels GET oder POST übergeben werden. Die Parameter müssen URL encodiert sein.

Folgende Parameter werden unterstützt:

url

Die zu kürzende URL.

Unterstützt werden http: und https: Web-Adressen mit einer maximalen Länge von derzeit 768 Zeichen. Die maximal erlaubte Länge ist ein von uns auferlegter Wert, der den Missbrauch unseres Dienstes verhindern soll.

key (optional)

Falls gewünscht kann mit diesem Parameter eine Link-Kennung gewählt werden. Wenn der Parameter nicht angegeben wird, so wird eine zufällige Kennung erzeugt.

Die Kennung darf die Zeichen a-z, A-Z, 0-9 und '-' enthalten und muss eine Länge von 4 bis 32 Zeichen haben.

title (optional)

Dieser optionale Seitentitel wird für den Link gespeichert. Der Einsatz dieses Parameters macht insbesondere für Benutzer mit Kundenkonto in unserem System Sinn. Siehe dazu auch den Abschnitt "Autentifizierung".

Der Titel darf eine maximale Länge von 256 Zeichen haben. Falls er länger ist, so wird er nach 256 Zeichen abgeschnitten.

Antwort

Ohne weitere Angaben erfolgt die Rückgabe als einzeilige "Plain Text" Antwort. Fehlercodes werden als HTTP Status Code und als Text-Meldung im Antwort-Body zurückgegeben.

Ist der Status-Code 200, so enthält der Antwort-Body die erzeugte Kurz-URL:

HTTP/1.1 200 OK

http://piep.net/abcd

Ist ein Fehler aufgetreten, so enthält die Antwort eine Fehler-Kennung und eine kurze, englischsprachige Fehler-Beschreibung. Die beiden Werte werden durch " | " (Space, Pipe, Space) voneinander getrennt:

HTTP/1.1 400 OK

URL_MISSING | Required parameter "url" is missing.

Eine Liste der möglichen Fehler-Kennungen:

HTTP Code Kennung Beschreibung
500 INTERNAL_ERROR Es ist ein interner Fehler aufgetreten.
403 KEY_FORBIDDEN Der gewünschte "key" kann nicht verwendet werden. Auch Sicherheitsgründen sind manche Worte als Key nicht erlaubt.
403 KEY_ILLEGAL Der gewünschte "key" enthält nicht erlaubte Zeichen. Erlaubt sind nur alphanumerische Zeichen und das Minus.
403 KEY_TOO_LONG Der gewünschte "key" ist zu lang. Er darf maximal 32 Zeichen lang sein.
403 KEY_TOO_SHORT Der gewünschte "key" ist zu kurz. Er muss mindestens 4 Zeichen lang sein.
409 KEY_USED Der gewünschte "key" ist bereits vergeben.
400 URL_ILLEGAL Die angegebene lange URL ist nicht gültig.
400 URL_MISSING Der Parameter "url" wurde nicht angegeben oder ist leer.
400 URL_TOO_LONG Der Parameter "url" darf maximal 768 Zeichen Lang sein.
500 SERVERFAULT Es ist ein interner Fehler aufgetreten.

Auf Wunsch ist es auch möglich, die Rückgabe in einem anderen Format zu erhalten. Dazu muss nur die aufgerufene API-URL ein klein wenig verändert werden:

http://api.piep.net/api/shorturl/v1/shorten.[format]

[format] ist hier ein Platzhalter für...

  • ini
  • json
  • php
  • serialize
  • xml

In all diesen Fällen hat die Antwort immer den HTTP Status Code 200. Fehlercodes werden im Antwort-Body mitgeliefert.

Beispiele:

  • ini

    [result]
    shorturl=http://piep.net/abcd
    error=false
    error_msg=OK
    error_usermsg=Link created

  • json

    {
    "shorturl":"http:\/\/piep.net\/abcd",
    "error":false,
    "error_msg":"OK",
    "error_usermsg":"Link Created"
    }

  • php

    array (
    'shorturl' => 'http://piep.net/abcde',
    'error' => false,
    'error_msg' => 'OK',
    'error_usermsg' => 'Link Created',
    );

  • serialize (kann mit dem PHP-Kommando unserialize verarbeitet werden)

    a:4:{s:8:"shorturl";s:20:"http://piep.net/abcd"; s:5:"error";b:0; s:9:"error_msg";s:2:"OK"; s:13:"error_usermsg";s:12:"Link Created";}

  • xml

    <result>
    <shorturl>http://piep.net/abcd</shorturl>
    <error>false</error>
    <error_msg>OK</error_msg>
    <error_usermsg>Link Created</error_usermsg>
    </result>

Autentifizierung

coming soon...