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

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), nutzen Sie bitten den Accept-Language-Header des HTTP-Protokolls.

Accept-Language: de

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
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