clockodo REST-API
Unsere API öffnet clockodo für andere Systeme. Rechnungs- und Projektmanagement-Anwendungen oder eigene Shell-Skripte etwa sind nützliche Mash-ups mit clockodo. Als REST-API ermöglicht die Schnittstelle, clockodo-Daten über HTTP und JSON abzufragen, zu verändern und die Stoppuhr zu steuern.
Adresse der clockodo-API
Zugriff auf die Schnittstelle erhalten Sie über folgende Adresse:
https://my.clockodo.com/api/[Ressourcen-Typ]
Hierbei stellt der Ressourcen-Typ eine Klasse Ihrer Daten dar. Im Menü finden Sie zu jedem Ressourcen-Typ genauere Beschreibungen. So finden Sie beispielsweise unter "/api/entries" detaillierte Informationen dazu, wie Sie den Ressourcentyp "entry" verwalten können, wobei "entries" Zeiteinträge in Ihrer clockodo-Umgebung sind.
Sobald Sie eine bestimmte Ressource anfragen, also z.B. Informationen zu genau einem Zeiteintrag abfragen, verändert sich die URL wie folgt:
https://my.clockodo.com/api/[Ressourcen-Typ]/[Ressourcen-ID]
HTTP-Verben
Um der API mitzuteilen welche Operationen Sie auf den Ressourcen ausführen möchten, werden die sogenannten Verben des HTTP-Protokolls genutzt. Folgende Operationen sind üblicherweise möglich:
| GET | Liste aller Ressourcen des gewählten Ressourcen-Typs abfragen |
|---|---|
| GET, mit Übergabe einer Ressourcen-ID in der URL | Genau eine Ressource abfragen |
| POST | Genau eine Ressource abfragen |
| PUT, mit Übergabe einer Ressourcen-ID in der URL | Eine Ressource aktualisieren/bearbeiten |
| DELETE | Eine Ressource löschen (bei den meisten Ressourcen erlaubt die clockodo-API jedoch kein endgültiges Löschen, sondern deaktiviert die Ressource) |
Authentifizierung
Um über die API Zugriff auf Ihre Daten zu erhalten, müssen Sie sich bei der API mit dem sogenannenten API-Key authentifizieren. Dafür gibt es zwei verschiedene Arten:
Über folgende HTTP-Header:
X-ClockodoApiUser: [E-Mail-Adresse] X-ClockodoApiKey: [API-Key]
Oder mittels der Basis-Authentifizierung des HTTP-Protokolls:
User: [E-Mail-Adresse] Passwort: [API-Key]
Für jeden Mitarbeiter steht ein eigener API-Zugang bereit, der die jeweiligen Zugriffsrechte des Benutzers berücksichtigt.
Jeder Mitarbeiter findet seinen API-Key im Menüpunkt "Meine Daten" in seiner clockodo-Umgebung.
Client-Identifikation
Jede Anfrage an unsere API muss eine Identifikation der aufrufenden Anwendung, samt der E-Mail-Adresse eines technischen Ansprechpartners enthalten. Hierfür muss der folgende HTTP-Header genutzt werden:
X-Clockodo-External-Application: [Name der Anwendung oder Ihres Unternehmens];[E-Mail-Adresse]
X-Clockodo-External-Application: Clickbits;admin@clickbits.de
Lokalisierung: Übersetzungen & Formate
Einige Rückgaben der API erfolgen lokalisiert. So z.B. das Texte die ein Datum beschreiben, Fehlermeldungen und ähnliches. Um zwischen den verfügbaren Sprachen umzuschalten (de/en/fr), nutzen Sie bitten den Accept-Language-Header des HTTP-Protokolls.
Accept-Language: de
Lokalisierung: Zeitzone
Alle Zeitstempel (Daten mit Uhrzeiten) werden immer in die Zeitzone des anfragenden Benutzer lokalisiert und im Format "YYYY-MM-DD HH:MM:SS" zurückgegeben.
Alternativ können Sie Zeitstempel jedoch normalisiert in Weltzeit (UTC) abfragen und auch alle Zeitstempel an die clockodo-API in dieser Form absenden.
Setzen Sie dafür den HTTP-Header "X-ClockodoEnableIsoUtcDateTimes" auf "1".
Aktivieren von UTC-Zeitstempeln im ISO-Format (YYYY-MM-DDTHH:MM:SSZ)X-ClockodoEnableIsoUtcDateTimes: 1
Response-Codes
Die API antwortet auf Anfragen mit den Status-Codes des HTTP-Protokolls. Bei Fehlern finden Sie außerdem zusätzliche Fehlerinformationen in der Antwort.
| 200 - OK | Die Anfrage war erfolgreich |
|---|---|
| 400 - Bad Request | Die Anfrage war fehlerhaft (z.B. fehlende Parameter) |
| 401 - Unauthorized | Authentifizierung nicht erfolgreich |
| 404 - Not found | Die angefragte Ressource konnte nicht gefunden werden |
| 405 - Method Not Allowed | Der angefragte Endpunkt kann nicht verwendet werden |
| 409 - Conflict | Eine Ressource mit den Daten existiert bereits |
| 500 - Internal Server Error | Es ist ein unbekannter Fehler aufgetreten |
Seitenweise Ausgabe
Bestimmte Ressourcen liefern im Zweifel sehr viel Daten zurück. Daher ist für diese Ressourcen eine seitenweise Ausgabe aktiv, sodass Ihnen pro Abruf maximal 1000 Elemente zurückgegeben werden. Über den zusätzlichen Anfrage-Parameter "page" können Sie dann auf weitere Elemente zugreifen.
| Zusätzlicher-Anfrage-Parameter | page (integer) |
|---|
'paging': {
'items_per_page': [integer],
'current_page': [integer],
'count_pages': [integer],
'count_items': [integer]
}Hinweis: Derzeit ist die seitenweise Ausgabe nur für die Ressource "entries" aktiv.
Beispiel-Aufrufe
curl -v -X GET \ -u [E-Mail-Adresse]:[API-Key] \ 'https://my.clockodo.com/api/services'
curl -v -X GET \ -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ -H 'X-ClockodoApiKey: [API-Key]' \ 'https://my.clockodo.com/api/services'
curl -v -X POST \ -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ -H 'X-ClockodoApiKey: [API-Key]' \ --data "name=Testleistung" \ 'https://my.clockodo.com/api/services'