REST-API

Die clockodo-API ermöglicht die Anbindung von clockodo an andere Systeme. Rechnungs- und Projektmanagement-Anwendungen oder eigene Shell-Skripte sind Beispiele für nützliche Mash-Ups mit clockodo.

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

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)

Zusätzlicher Inhalt der Antwort

'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

Beispiel für den Abruf aller Leistungen mit cURL unter Nutzung der Basis-Authentifizierung

curl -v 
  -X GET \ 
  -u [E-Mail-Adresse]:[API-Key] \ 
  'https://my.clockodo.com/api/services'

Beispiel für den Abruf aller Leistungen mit cURL mit Authentifizierung über den HTTP-Header

curl -v 
  -X GET \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  'https://my.clockodo.com/api/services'

Beispiel für das Anlegen einer Leistung

curl -v 
  -X POST \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  --data "name=Testleistung" \
  'https://my.clockodo.com/api/services'