Login English

Entwickler, sei gegrüßt! Die mite.api freut sich auf deine Hacks. Welche Funktionen wie zur Verfügung stehen, erfährst du hier im Dokumentationsbereich.

Überblick

Einführung

Die mite.api ist nach den Prinzipien von REST aufgebaut. Wir verwenden vorhersehbare, ressourcenorientierte URIs, die du mit HTTP-Verben lesen und modifizieren kannst, und geben HTTP-Status-Codes aus, wenn ein Fehler auftritt.

Alle Zugriffe erfolgen per HTTPS auf eine accountspezifische Domain:

:account_name.mite.yo.lk

Im Folgenden verwenden wir als Account-Namen und damit Subdomain demo; bitte ersetze diesen mit deinem eigenen Account-Namen.

Unterstützte Formate

Die mite.api unterstützt JSON und XML zum Senden und Empfangen von Daten. Wir empfehlen generell die Verwendung von JSON, da es kompakter ist und von unseren Servern wesentlich schneller und effizienter generiert werden kann.

Das Format wird als Suffix in der URL mit angegeben; der HTTP-Header Accept wird derzeit nicht unterstützt:

https://demo.mite.yo.lk/users.json
https://demo.mite.yo.lk/users.xml

Alle Daten und Zeitstempel werden sowohl in JSON als auch in XML im Format ISO 8601 ausgegeben:

YYYY-MM-DD
YYYY-MM-DDTHH:MM:SSZ

Zeitstempel werden immer in der Zeitzone ausgegeben, die im Account eingestellt wurde.

HTTP-Verben

Die folgenden HTTP-Verben werden von der mite.api genutzt:

HEAD Gibt nur die HTTP-Header einer Ressource zurück, nicht jedoch den Body.
GET Um eine Ressource zu lesen
POST Um eine neue Ressource zu erstellen
PATCH Um eine bestehende Ressource zu modifizieren. Die übergebenen Attribute werden partiell angewendet, so dass nicht die komplette Ressource mitgesendet werden muss. Das PATCH-Verb ist noch relativ neu und wird nicht von allen HTTP-Clients unterstützt; daher ist es auch möglich ersatzweise PUT zu verwenden.
DELETE Um eine Ressource zu löschen

Tools

Alle Daten können mit einem normalen Browser ausschließlich gelesen werden. Firefox eignet sich hierzu besonders gut, da er XML inline darstellen kann. Um JSON-Daten ebenso inline darstellen zu können, empfehlen wir die Installation des Add-Ons JSONView.

Um alle Features der API zu nutzen, empfiehlt sich ein Kommandozeilen-Tool wie cURL oder HTTPie.

Wer es mit der Kommandozeile nicht so hat, kann auch auf das Firefox-Plugin RESTClient oder die Rest Console für Google Chrome zurückgreifen. Besonders empfehlenswert ist unser Meinung nach auch der kostenpflichtige REST-Client Paw für den Mac.

Authentifizierung

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: Du findest diese Option direkt in mite, per Klick auf den eigenen Benutzernamen rechts oben. Aktiviere dort die entsprechende Checkbox und sichere die Änderung. So erhältst du deinen persönlichen API-Schlüssel.

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

Wichtig: Auch Sicherheitsgründen empfiehlt sich in jedem Fall die Verwendung des API-Schlüssels. Dein Passwort solltest du nur in Ausnahmefällen, etwa in einem kurzen Skript, verwenden.

Mit E-Mail und Passwort

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

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

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

Mit dem API-Schlüssel

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

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

oder als Parameter api_key in einem GET-Request mitsenden:

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

Deinen User-Agent angeben

Bitte setze bei allen Zugriffen den HTTP-Header User-Agent, um deine Anwendung oder dein Skript eindeutig zu kennzeichnen. Im Idealfall enthält der Header den Anwendungsnamen und einen Link oder eine E-Mail-Adresse, damit wir bei Problemen schnell mit dir Kontakt aufnehmen können. Bonus-Punkte gibt es, wenn du zusätzlich noch eventuell verwendete Bibliotheken inklusive deren Version mit angibst. Ein Beispiel:

User-Agent: mite.app/v1.1 (https://github.com/yolk); mite-rb/0.5.3

Die Angabe des User-Agent könnte von uns in einer zukünftigen Version der API erzwungen werden. Daher empfiehlt es sich, schon jetzt immer den HTTP-Header zu setzen.

Ressourcen lesen

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

Einzelne Ressource

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

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

Liste von mehreren Ressourcen

Eine Liste wird über den Ressourcen-Pfad gelesen:

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

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

Ressourcen schreiben

Daten werden mittels der HTTP-Methoden POST, PATCH und DELETE geschrieben. Genau wie zur Ausgabe werden dabei die beiden Formate JSON und XML unterstützt.

Bitte beachte: Das verwendete Format MUSS bei jedem schreibenden Request mittels des Headers Content-Type mit angegeben werden. Im Falle von JSONXML muss der Header auf application/jsonxml gesetzt werden.

Eine Ressource erstellen

curl -v -X POST \
-H 'X-MiteApiKey: DEIN_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"service":{"name":"Dokumentation"}}' \
https://demo.mite.yo.lk/services.json
curl -v -X POST \
-H 'X-MiteApiKey: DEIN_API_KEY' \
-H 'Content-Type: application/xml' \
-d '<service><name>Dokumentation</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 'Dokumentation'. Als Antwort erhältst Du den Status 201 Created, einen Location-Header mit der URL der gerade erstellten Ressource und im Response-Body die komplette Ressource.

Eine Ressource modifizieren

Eine bereits angelegte Ressource wird mit der PATCH-Methode bearbeitet:

curl -v -X PATCH \
-H 'X-MiteApiKey: DEIN_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"service":{"archived":true}}' \
https://demo.mite.yo.lk/services/1.json
curl -v -X PATCH \
-H 'X-MiteApiKey: DEIN_API_KEY' \
-H 'Content-Type: application/xml' \
-d '<service><archived type="boolean">true</archived></service>' \
https://demo.mite.yo.lk/services/1.xml

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

Eine Ressource löschen

Das Löschen einer Ressource über die DELETE-Methode funktioniert ähnlich, natürlich ohne Daten im Request-Body – somit entfällt in diesem Fall die Verwendung des Headers Content-Type:

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

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

HTTP-Status-Codes

Im folgenden findest du eine Liste der HTTP-Status-Codes, die die mite.api ausgibt, und wie du diese interpretieren kannst. Im Allgemeinen stehen 200er-Codes für einen erfolgreichen Request, 400er für einen Fehler in den Request-Daten (zum Beispiel fehlt ein zwingend anzugebender Parameter) und 500er für einen Fehler auf unseren Servern.

200 OK Eine erfolgreiche Anfrage
201 Created Eine Ressource wurde erfolgreich erstellt.
400 Bad Request Liegt meist an einem Syntax-Fehler im Request-Body
401 Unauthorized Falscher oder fehlender API-Schlüssel.
403 Forbidden Dem authorisierte Nutzer ist es nicht erlaubt die gestellte Anfrage auszuführen. Eventuell hat der Nutzer nur die Rolle eines Zeiterfassers?
404 Not Found Die Ressource konnte nicht gefunden werden. In manchen Fällen, in denen der authorisierte Nutzer eine bestimmte Rolle benötigt um die Anfrage auszuführen, wird statt eines 403 Forbidden ein 404 Not Found ausgegeben. Dies geschieht um das versehentliche Preisgeben von sensiblen Informationen zu verhindern.
406 Not Acceptable Das Format der Anfrage wird nicht unterstützt. Verwende stattdessen JSON oder HTML.
422 Unprocessable Entity Liegt meist an fehlenden, aber zwingend erforderlichen Attributen.
423 Locked Du versuchst einen als "Abgeschlossen" markierten Zeiteintrag zu modifizieren.
500, 502, 503 Server Error Da lief wohl auf unseren Servern etwas schief. Wiederhole die Anfrage nach kurzer Zeit und melde dich bei uns, falls der Fehler dauerhaft auftritt.

Client-Fehler

In den meisten Fällen lässt sich aus dem zurückgegebenen HTTP-Status-Code der Fehler bereits ableiten. Für weitere Details geben wir eine zusätzliche Error-Ressource im Body aus. Einige Beispiele:

Wenn du einen nicht existenten Account-Namen für die Subdomain benutzt:

Status: 404 Not Found
{
   "error": "Hoppla! Den Account 'unbekannt' konnten wir nicht finden."
}
Status: 404 Not Found
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Hoppla! Den Account 'unbekannt' konnten wir nicht finden.</error>
</errors>

Wenn du keine oder falsche Authentifizierungsdaten mitschickst:

Status: 401 Unauthorized
{
   "error": "Dir wurde der Zugriff verweigert. Bitte überprüfe deine Anmeldedaten."
}
Status: 401 Unauthorized
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Dir wurde der Zugriff verweigert. Bitte überprüfe deine Anmeldedaten.</error>
</errors>

Wenn beim Modifizieren oder Erstellen einer Ressource zwingend erforderliche Attribute fehlen:

Status: 422 Unprocessable Entity
{
   "error": "Bitte gib dem Projekt einen Namen."
}
Status: 422 Unprocessable Entity
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Bitte gib der Projekt einen Namen.</error>
</errors>

Wenn du eine Ressource abfragst, die inzwischen gelöscht wurde:

Status: 404 Not Found
{
   "error": "Der Datensatz ist nicht vorhanden."
}
Status: 404 Not Found
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Der Datensatz ist nicht vorhanden.</error>
</errors>

Wenn du invalides JSONXML im Body der Anfrage verwendest:

Status: 400 Bad Request
{
   "error": "Die von dir gesendeten Daten sind kein valides JSON:: unexpected token at '{\"service: {}}'"
}
Status: 400 Bad Request
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Die von dir gesendeten Daten sind kein valides XML: Start tag expected, '<' not found</error>
</errors>

HTTP-Caching

Die meisten Antworten unserer API enthalten einen ETag HTTP-Header. Dessen Wert kann bei weiteren Anfragen derselben Ressource im If-None-Match Header angegeben werden. Wenn die Ressource sich nicht geändert hat, gibt unsere API ein 304 Not Modified zurück. Dieses Feature ist besonders nützlich, wenn du oft die gleichen Ressource mehrfach abfragst und es sich dabei um eine potentiell sehr umfangreiche Liste handelt.

Beispiel

$ curl -i https://demo.mite.yo.lk/services/1.json
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

$ curl -i https://demo.mite.yo.lk/services/1.json \
-H 'If-None-Match: W/"883112cb2ba78a99e4e562de2a6dd305"'
HTTP/1.1 304 Not Modified
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}
$ curl -i https://demo.mite.yo.lk/services/1.xml
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

$ curl -i https://demo.mite.yo.lk/services/1.xml \
-H 'If-None-Match: W/"883112cb2ba78a99e4e562de2a6dd305"'
HTTP/1.1 304 Not Modified
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

Bibliotheken

Ruby mite.rb Offizielle Ruby-Bibliothek
PHP MiteEleven von SysEleven
PHP mite.php von Thomas Klein
PHP Mitey von Stefan Pasch
Node.js mite-api von Marcel Meyer
Objective-C CocoaMite von Heiko Dreyer
.NET mite.net von Christoph Keller
Java JMite von Oliver Gierke

Open-Source Beispiele

Ruby mite.cmd Ermöglicht die Bedienung von mite von der Kommandozeile aus.
Von Lukas Rieder
Ruby git2mite Exportiert Commits aus git Richtung mite.
Von Alexander Lang
Python Git-Hooks Integriert mite mittels Hooks in git.
Von Thomas Spycher
Ruby Mantis2mite Verknüpft mite mit dem Projektmanager Redmine.
Von Thomas Klein
Python Trac2mite Verknüpft mite mit dem Bugtracker Trac.
Von Thomas Klein
PHP Mantis2mite Verknüpft mite mit dem Bugtracker Mantis.
Von Thomas Klein
.NET TrelloMite Verknüpft mite mit dem Todo-Tool Trello.
Von Hannes Sachsenhofer
Java mite4java Hilft beim Erstellen von Reports samt Excel-Export.
Von Simon Martinelli
Ruby CoReMite Erstellt Reports in der Kommandozeile.
Von Christopher de Bruin