API-Grundlagen

Die Werkstatt42-API ist ein RESTful Webservice. Alle Daten wie Projekte, Whiteboards oder Dateien besitzen eine eigene URL und können mit den HTTP-Verben GET, POST, DELETE und PUT ausgelesen bzw. bearbeitet werden.

Mit GET werden Daten gelesen, mit POST neue erstellt, mit DELETE gelöscht und mit PUT verändert. Weitere Informationen zu REST gibt es bei Wikipedia oder InfoQ.

Die URL der API

[http|https]://{plattform}.werkstatt42.de/api/{ressource}[/{id}][/{methoden}]

Parameter Beschreibung
{plattform}Die ID der Plattform. Falls die Adresse https://team42.werkstatt42.de lautet, wäre diese team42
{ressource}Der Name der Ressource, z.B. projects. Dieser wird auf den folgenden Seiten genannt
{id}Die ID der Ressource, falls es um eine einzelne geht (optional)
{methoden}Optionale weitere Methoden. Diese werden auf den folgenden Seiten genannt.

Beispiel: https://team42.werkstatt42.de/api/projects

Formate

Die API versteht die Formate XML und JSON. Je nach gewünschtem Format bei schreibenden Requests muss der jeweilige Content-Type HTTP-Header gesetzt werden: application/xml oder application/json. Welches Format man als Antwort bekommt, bestimmt man mit dem Accept HTTP-Header oder mit dem Parameter ?format=[xml|json]. Zur Vereinfachung kann das Format aber auch am Ende der Ressource in der URL angegeben werden: https://{plattform}.werkstatt42.de/api/projects.xml oder https://{plattform}.werkstatt42.de/api/projects/1.json.

Authentifizierung

Die API benötigt eine Authentifizierung durch bestehende Mitglieder auf der Plattform. Das Mitglied muss den API-Zugriff in seinem Profil unter Einstellungen > Profil > API freischalten und dann einen persönlichen API-Schlüssel generieren. Dieser API-Schlüssel ist das "Passwort" für die Nutzung der API.

Anders als bei der Nutzung im Browser, ist jeder API-Zugriff unabhängig und zustandslos. Daher muss der API-Schlüssel bei jedem Request mitgesendet werden. Es werden also keine Sitzungen gespeichert.

Der API-Schlüssel kann auf zwei Arten mitgesendet werden:

Als Parameter

https://{plattform}.werkstatt42.de/api/projects?api_key={apischlüssel}

Als HTTP-Header

X-PlatformApiKey: {apischlüssel}

Sicherheit

Ob der Zugriff auf die API über eine SSL-verschlüsselte Verbindung (https) erfolgen kann, hängt davon ab, ob in dem entsprechenden Tarif der Plattform SSL-Unterstützung (erweiterte Sicherheit) gebucht wurde. Es wird empfohlen immer eine verschlüsselte Verbindung zu verwenden, da sonst unter Umständen die übertragenen Daten mitgelesen werden können.

Tools

Zum Testen der Requests über die API reicht für GET-Requests ein normaler Browser. Im Firefox werden die XML-Daten übersichtlich als Baumstruktur dargestellt. Für die anderen HTTP-Verben (POST, PUT, DELETE) kann entweder das Kommandozeilen-Tool curl oder das grafische Firefox-Plugin RESTClient verwendet werden.

Daten lesen

Eine Liste der Projekte auf der Plattform wird mit curl so gelesen:

curl -H 'X-PlatformApiKey:{apischlüssel}' \
https://{plattform}.werkstatt42.de/api/projects.xml

Eine einzelne Ressource kann man durch das Anhängen der ID der Ressource auslesen:

curl -H 'X-PlatformApiKey:{apischlüssel}' \
https://{plattform}.werkstatt42.de/api/projects/1.xml

Daten schreiben

Daten werden mittels der HTTP-Verben POST, PUT und DELETE geschrieben. Um das eingehende Format der Daten anzugeben, muss man den Header "Content-type: application/xml" oder "Content-type: application/json" mitsenden. So erstellt man mit der API ein neues Projekt:

curl -v -X POST -H 'X-PlatformApiKey:{apischlüssel}' \
-H 'Content-Type: application/xml' \
-d '<project><name>Neues Projekt</name></project>' \
https://{plattform}.werkstatt42.de/api/projects

Alternativ kann auch JSON verwendet werden, wenn "Content-Type: application/json" mitgesendet wird:

curl -v -X POST -H 'X-PlatformApiKey:{apischlüssel}' \
-H 'Content-Type: application/json' \
-d '{"project":{"name":"Neues Projekt"}}' \
https://{plattform}.werkstatt42.de/api/projects

Beide Requests erzeugen ein neues Projekt mit dem Namen "Neues Projekt" und liefern als Statuscode "201 Created" und im Request-Body die Projekt-Ressource zurück.

Ein bestehendes Objekt kann mit der PUT-Methode bearbeitet werden:

curl -v -X PUT -H 'X-PlatformApiKey:{apischlüssel}' \
-H 'Content-Type: application/json' \
-d '{"project":{"name":"Bearbeitetes Projekt"}}' \
https://{plattform}.werkstatt42.de/api/projects/1

War die Aktion erfolgreich, kommt der Statuscode "200 OK" zurück.

Das Löschen funktioniert analog mit der DELETE-Methode:

curl -v -X DELETE -H 'X-PlatformApiKey:{apischlüssel}' \
-H 'Content-Type: application/json' \
https://{plattform}.werkstatt42.de/api/projects/1

War die Aktion erfolgreich, kommt der Statuscode "200 OK" zurück.

Fehler

Tritt in der API ein Fehler auf, so liegt der zurückgegebene Statuscode im 400er oder 500er Bereich. Meist lässt sich durch ihn bereits erkennen, wo das Problem lag. Der Body gibt zusätzlich eine kurze Beschreibung des Fehlers:

Response: 404 Not Found

Response: 422 Unprocessable Entity

Werkstatt42 ist eine webbasierte Groupware zur Online Zusammenarbeit, effizienten Gruppenarbeit und eine Online Projektmanagement Software. Das bedeutet Sie können Ihre Projektarbeit und Projektplanung gemeinsam online erledigen, egal von wo. Auf Englisch nennen sich diese webbasierte Software auch Online Collaboration Software. Die Webanwendung ist eine Software zur Projektverwaltung, sowie ein Projekt Management System und eine einfache Projektmanagement Software, d.h. sie ist leicht zu bedienen und benötigt keine Einarbeitungszeit.