• Einführung
• Unterstützte Formate
• HTTP-Verben
• Tools
• Authentifizierung
• Deinen User-Agent angeben
• Ressourcen lesen
• Ressourcen schreiben
• HTTP-Status-Codes
• Client-Fehler
• HTTP-Caching
• Bibliotheken
• Open-Source Beispiele

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:

https://{account_name}.mite.de

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.de/users.json

https://demo.mite.de/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:

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 RapidAPI 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 [email protected]:DEIN_PASSWORT \
https://demo.mite.de/projects.json

curl -u [email protected]:DEIN_PASSWORT \
https://demo.mite.de/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.de/projects.json

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

oder als Parameter api_key in einem GET-Request mitsenden:

curl https://demo.mite.de/projects.json?api_key=DEIN_API_KEY

curl https://demo.mite.de/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.de/services/1.json

curl -v -H 'X-MiteApiKey: DEIN_API_KEY' \
https://demo.mite.de/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.de/services.json

curl -v -H 'X-MiteApiKey: DEIN_API_KEY' \
https://demo.mite.de/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.de/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.de/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.de/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.de/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.de/services/1.json

curl -v -X DELETE -H 'X-MiteApiKey: DEIN_API_KEY' \
https://demo.mite.de/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.

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:

{
   "error": "Hoppla! Den Account 'unbekannt' konnten wir nicht finden."
}

<?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:

{
   "error": "Dir wurde der Zugriff verweigert. Bitte überprüfe deine Anmeldedaten."
}

<?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:

{
   "error": "Bitte gib dem Projekt einen Namen."
}

<?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:

{
   "error": "Der Datensatz ist nicht vorhanden."
}

<?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:

{
   "error": "Die von dir gesendeten Daten sind kein valides JSON:: unexpected token at '{\"service: {}}'"
}

<?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.de/services/1.json
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

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

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

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

Bibliotheken

Open-Source Beispiele