API zur Online Zeiterfassung: REST-Schnittstelle

(Technische Beschreibung für Softwareentwickler)

Die Zeiterfassung bietet eine einfache REST-Schnittstelle für Softwareentwickler zum Erstellen von Zeiteinträgen. Die Schnittstelle ist als REST-Service implementiert und auch geeignet für die Anbindung von Stempeluhren.

Voraussetzungen:

Das REST-API muss in den Einstellungen der Zeiterfassung (Reiter Sicherheit) aktiviert und ein Passwort gesetzt werden. Hinweis: Das selbe Passwort wird auch für die Webservice-Schnittstelle verwendet.

Technische Beschreibung

Eine Test-Ressource ist erreichbar unter: https://www.goodtimetracking.com/goodtime-rs/api/hello/sayhello

Eine Test-Ressource für das Login ist erreichbar unter: https://www.goodtimetracking.com/goodtime-rs/api/hello/securedSayhello Für diesen Aufruf muss vorher https://www.goodtimetracking.com/goodtime-rs/goodtime-rs/api/login aufgerufen werden.

Ein einfacher Testclient in Java für alle verfügbaren Funktionen als Zip-Datei oder Tar-Datei.

Beschreibung der Ressourcen

Ressource @GET /api/hello/sayhello

Diese Ressource zum Testen gibt ein Hallo zurück.

Parameter:
Keine
Rückgabewert:
String
'Hello!'

Ressource @GET /api/hello/securedSayhello

Diese Ressource kann zum Testen des Logins verwendet werden. Das Login muss zuvor aufgerufen werden.

Parameter:
Keine
Rückgabewert:
String
'Secured Hello!'

Methode @POST /api/login

Diese Ressource kann für das Login verwendet werden.

Parameter:
{loginemail, apipassword}
Als loginemail wird die Loginemail des Admins verwendet. Das API-Passwort wird in den Einstellungen (Reiter 'Sicherheit') gesetzt werden. Beispiel: {"loginemail": "admin@gtdemo.de", "apipassword": "12345678"}
Rückgabewert:
JSON Web Token
Das zurückgegebene Token muss bei jedem Request zur Authentifikation als Header mitgeschickt werden.

Methode @GET /api/time/timecategories

Diese Ressource liefert eine Liste von Zeitarten zurück.

Parameter:
Keine
Rückgabewert:
[{id, name}, ...]
Die Liste der Zeitarten im Format: Id der Zeitart, Name der Zeitart. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Arbeitszeit"}, ...]

Methode @GET /api/time/users

Diese Ressource liefert eine Liste der Loginemails aller Benutzer zurück.

Parameter:
Keine
Rückgabewert:
[{loginemail}, ...]
Die Liste der Loginemails aller Benutzer. Beispiel: [{"admin@gtdemo.de"}, ...]

Methode @GET /api/time/projects

Diese Ressource liefert die Liste der Projekte zurück.

Parameter:
Keine
Rückgabewert:
[{id, name}, ...]
Die Liste der Projekte im Format: Id des Projekts, Name des Projekts. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demoprojekt"}, ...]

Methode @GET /api/time/projects/{useremail}

Diese Ressource liefert eine Liste der Projekte für einen bestimmten Benutzer zurück.

Parameter:
{useremail}
Die Loginemail des fraglichen Benutzers. Beispiel: @GET /projects/maier@gtdemo.de
Rückgabewert:
[{id, name}, ...]
Die Liste der Projekte im Format: Id des Projekts, Name des Projekts. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demoprojekt"}, ...]

Methode @POST api/time/createtimeentry

Mit dieser Ressource kann man einen neuen Zeiteintrag erzeugen.

Parameter:
{starttime, endtime, useremail, timetypeid, projectid}
starttime und endtime müssen im folgenden Format angegeben werden: JJJJ-TT-MMTHH:MM:00 - z.B.: '2007-23-03T10:15:00'. Die Angabe einer projectid ist optional. Beispiel für einen Zeiteintrag: {"starttime": "2007-23-03T10:15:00", "endtime": "2007-23-03T18:21:00", "useremail": "maier@gtdemo.de", "timetypeid": "83be5360-6067-4a09-a970-1ff2413d7101", "projectid": "2aeba501-ca09-41b2-a938-654d178914e4"}
Rückgabewert:
Keiner