ProSonata API
Folgende HTTP-Methoden stehen für Projektzeiten zur Verfügung:
Zugriff für alle Benutzergruppen.
Alle nicht-Administratoren erhalten nur ihre eigenen Arbeitszeiten.
Nur Administratoren können Arbeitszeiten aller Benutzer erstellen/bearbeiten/löschen.
Alle Benutzer können ihre eigenen Arbeitszeiten erstellen/bearbeiten/löschen.
GET /api/v1/workingtimes
Antwort:
{
"meta": {
"status": 200,
"perPage": 100,
"page": 1,
"totalCount": 5612,
"requestUserID": 1,
"requestUsername": "Max",
"usergroupName": "Administrator",
"apiLimitRemaining": 456,
"apiLimitReset": 264
},
"data": [
{
"workingTimeID": 1,
"userID": 3,
"username": "Admin2",
"userFirstName": "Max",
"userLastName": "Mustermann",
"workingDate": "2021-02-13",
"dailyTimeStart": "09:15:00",
"dailyTimeEnd": "17:10:00",
"dayType": 0,
"halfHoliday": 0,
"homeOffice": 0,
...
},
...
]
}
Über Parameter kann gefiltert werden:
GET /api/v1/workingtimes?userID=3
| Parameter | Beschreibung |
|---|---|
| userID | ID eines Benutzers Sonderwert: String »myself« für Zeiten des anfragenden Benutzeraccounts |
| username | Benutzername |
| workingDate | Datum des Zeiteintrags durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen |
| workingDate2 | zweite Datumsangabe, um die Suchanfrage weiter einzuschränken durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen |
| dayType | Tagestyp 0 = Arbeit 1 = Urlaub 2 = Krankheit 3 = Feiertag 4 = Schule/Fortbildung 5 = Überstundenabbau 6 = Elternzeit / Mutterschutz / Pflegezeit / Sonstige |
| halfHoliday | halber Tag Urlaub 0 = nein 1 = ja |
| homeOffice | im Home-Office gearbeitet 0 = nein 1 = ja |
Nach folgenden Parametern kann sortiert werden (Sortierrichtung ggf. mit ASC bzw. DESC ergänzen):
workingTimeID, userID, workingDate
GET /api/v1/workingtimes/{id}
Antwort:
{
"meta": {
"status": 200,
"requestUserID": 1,
"requestUsername": "Admin1",
"usergroupName": "Administrator",
"apiLimitRemaining": 495,
"apiLimitReset": 462
},
"data": {
"workingTimeID": 1,
"userID": 3,
"username": "Max",
"userFirstName": "Max",
"userLastName": "Mustermann",
"workingDate": "2021-03-20",
"dailyTimeStart": "09:15:00",
"dailyTimeEnd": "17:10:00",
"dayType": 0,
"halfHoliday": 0,
"homeOffice": 0,
"break1Start": "12:00:00",
"break1End": "12:30:00",
"break2Start": null,
"break2End": null,
"break3Start": null,
"break3End": null,
"break4Start": null,
"break4End": null,
"dailyTimeTotal": 7.42,
"comments": "",
"editedByUserID": 0,
"workingTimeCreationDate": null,
"workingTimeViaApi": 0
}
}
POST /api/v1/workingtimes
Notwendige und mögliche Parameter im Body:
| Parameter | Beschreibung | Typ | Default-Wert | Pflichtfeld |
|---|---|---|---|---|
| userID | ID des Benutzers (nur Administratoren können Zeiten für andere Benutzer erfassen!) |
Int | ja | |
| workingDate | Datum des Zeiteintrags | Date | ja | |
| dailyTimeStart | Startzeitpunkt | Time | ja | |
| dailyTimeEnd | Endzeitpunkt | Time | ja | |
| dayType | Tagestyp 0 = Arbeit 1 = Urlaub 2 = Krankheit 3 = Feiertag 4 = Schule/Fortbildung 5 = Überstundenabbau 6 = Elternzeit / Mutterschutz / Pflegezeit / Sonstige |
Int | 0 | |
| halfHoliday | halber Tag Urlaub 0 = nein 1 = ja |
Int | 0 | |
| homeOffice | im Home-Office gearbeitet 0 = nein 1 = ja |
Int | 0 | |
| break1Start | Pause 1 Startzeit | Time | null | |
| break1End | Pause 1 Endzeit | Time | null | |
| break2Start | Pause 2 Startzeit | Time | null | |
| break2End | Pause 2 Endzeit | Time | null | |
| break3Start | Pause 3 Startzeit | Time | null | |
| break3End | Pause 3 Endzeit | Time | null | |
| break4Start | Pause 4 Startzeit | Time | null | |
| break4End | Pause 4 Endzeit | Time | null | |
| dailyTimeTotal | Gesamtzeit des Tages (in h) | Dec | ja | |
| comments | Anmerkungen (max. 100 Zeichen) |
String |
Angabe von Dezimalwerten mit Punkt als Trennzeichen.
Wichtig: Die übergebenen Werte (Startzeitpunkt, Endzeitpunkt und die resultierende dailyTimeTotal) müssen korrekt berechnet sein. Sie werden bei der Übernahme durch die API nicht zusätzlich auf Richtigkeit geprüft!
Ist für den Benutzer an dem angegebenen Tag bereits ein Eintrag vorhanden, wird dieser Tageseintrag gelöscht und anschließend der neue Eintrag erstellt.
Beispiel:
{
"userID": 1,
"workingDate": "2021-03-02",
"dailyTimeStart": "08:18:00",
"dailyTimeEnd": "16:48:00",
"dailyTimeTotal": 7.75,
"break1Start": "12:06:00",
"break1End": "12:51:00",
"comments": "eine Anmerkung"
}
PUT /api/v1/workingtimes/{id}
Es müssen nicht alle Parameter für eine Bearbeitung übergeben werden.
Es stehen die Parameter zum Erstellen der Ressource zur Verfügung. Die Werte userID und workingDate dürfen nicht verändert werden (um doppelte Einträge für einen Tag und Benutzer zu vermeiden). Bei Bedarf muss also ein Eintrag gelöscht und durch einen neuen Eintrag ersetzt werden.
DELETE /api/v1/workingtimes/{id}
Es müssen keine weiteren Parameter übergeben werden.