Anmelden

Es müssen keine separaten Benutzer für die API eingerichtet werden; Jeder Benutzer von mite kann auch die API für sein Konto freischalten.

Freigeschaltet wird der Zugang direkt in der Oberfläche, per Klick auf den eigenen Benutzernamen rechts oben. Aktivierst du dort die entsprechende Checkbox, erhältst du deinen persönlichen API-Schlüssel.

Zwei Möglichkeiten existieren, dich anzumelden: Nutze entweder deine normalen Zugangsdaten, die du auch zum Anmelden über die Weboberfläche benutzt, oder den automatisch generierten API-Schlüssel.

Die normalen Zugangsdaten gibst du einfach per HTTP-Basic als Benutzername/E-Mail und Passwort an. Ein einfaches Beispiel mit curl:

curl -u deine@mail.de:deinpasswort \
https://demo.mite.yo.lk/projects.xml

WICHTIG: Bitte verwende die korrekte Subdomain deines Accounts (in unserem Beispiel 'demo').

Um dich mit dem API-Schlüssel zu authentifizieren, kannst du diesen entweder als HTTP-Header "X-MiteApiKey" oder als Parameter "api_key" mitsenden:

curl -H "X-MiteApiKey: apischluessel" \
https://demo.mite.yo.lk/projects.xml

curl https://demo.mite.yo.lk/projects.xml?api_key=apischluessel

Sicherheit

Aus Sicherheitsgründen ist die API ausschließlich über HTTPS und somit verschlüsselt erreichbar.

Daten lesen

Daten werden immer mit der HTTP-Methode GET entweder in Listen oder als Einzel-Ressource gelesen.

Beim Lesen einer Einzel-Ressource setzt sich die URL aus dem Ressourcen-Pfad und der ID der Ressource zusammen:

curl -v -H 'X-MiteApiKey: apischluessel' \
https://demo.mite.yo.lk/services/1.xml

Eine Liste wird über den Ressourcen-Pfad gelesen:

curl -v -H 'X-MiteApiKey: apischluessel' \
https://demo.mite.yo.lk/services.xml

Wenn der Request erfolgreich war, bekommst du den Status 200 OK und die angeforderten Daten im XML-Format zurück.

Daten schreiben

Daten werden mittels der HTTP-Methoden POST, PUT und DELETE geschrieben. Genau wie zur Ausgabe wird dabei das XML-Format verwendet. Jeder schreibende Request sollte daher im Header "Content-type: application/xml" mitsenden, und die eigentlichen Daten fein säuberlich in XML-Tags verpackt im Body enthalten. Beispiel:

curl -v -X POST \
-H 'X-MiteApiKey: apischluessel' \
-H 'Content-Type: application/xml' \
-d '<service><name>Widget programmieren</name></service>' \
https://demo.mite.yo.lk/services.xml

Dies erzeugt mittels POST eine neue Ressource – in diesem Beispiel eine neue Leistung mit dem Namen 'Widget programmieren'. Als Antwort erhältst Du den Status 201 Created und im Response-Body das komplette Objekt.

Ein bereits angelegtes Objekt wird mit der PUT-Methode bearbeitet:

curl -v -X PUT \
-H 'X-MiteApiKey: apischluessel' \
-H 'Content-Type: application/xml' \
-d '<service><name>Widget testen</name></service>' \
https://demo.mite.yo.lk/services/1.xml

War die Bearbeitung erfolgreich, bekommst Du den Status 200 OK zurück.

Das Löschen eines Objekts über die DELETE-Methode funktioniert ähnlich, natürlich ohne Parameter im Request-Body:

curl -v -X DELETE -H 'X-MiteApiKey: apischluessel' \
https://demo.mite.yo.lk/services/1.xml

Auch hier liefert das erfolgreiche Löschen den Status 200 OK zurück.

Fehler

Tritt ein Fehler beim Bearbeiten eines Requests auf, wirft die mite.api immer einen Status-Code im 400er oder 500er-Bereich zurück; Meist lässt sich daraus bereits die Fehlerursache ablesen. Zusätzlich gibt mite jedoch noch eine kurze Klartext-Fehlermeldung im Response-Body aus:

Response : 404 Not Found

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Der Datensatz ist nicht vorhanden.</error>
</errors>

Response : 422 Unprocessable Entity

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Bitte gib dem Projekt einen Namen.</error>
</errors>