mite.api. Zeiten.

Entwickler, sei gegrüßt! Die mite.api freut sich auf deine Hacks. Welche Funktionen wie zur Verfügung stehen, erfährst du hier im Dokumentationsbereich.

Zeiten

Beispiele als XML anzeigen Beispiele als JSON anzeigen

Alle Zeiteinträge auflisten
Alle Zeiteinträge eines Tages auflisten
Zeiteinträge gruppieren
Einzelnen Zeiteintrag anzeigen
Einen Zeiteintrag erstellen
Einen Zeiteintrag bearbeiten
Einen Zeiteintrag löschen
Abgeschlossene Zeiteinträge

Bitte beachten: Ein Benutzer mit der Rolle Zeiterfasser hat nur Zugriff auf seine eigenen Zeiteinträge. Nur Administratoren können die Einträge anderer Nutzer modifizieren, löschen und für diese auch neue erstellen.

Alle Zeiteinträge auflisten

Listet alle Zeiteinträge aller Benutzer absteigend sortiert nach dem Datum (date_at) auf. Ein Zeiterfasser hat hingegen nur Zugriff auf die eigenen Zeiteinträge.

GET /time_entries.xml

GET /time_entries.json

Parameter

user_id	Filtere die Liste nach dem Benutzer. Erlaubt sind eine einzelne ID, current für den angemeldeten Benutzer sowie mehrere durch Komma getrennte IDs.
customer_id	Filtere die Liste nach dem Kunden. Erlaubt sind eine einzelne ID sowie mehrere durch Komma getrennte IDs.
project_id	Filtere die Liste nach dem Projekt. Erlaubt sind eine einzelne ID sowie mehrere durch Komma getrennte IDs.
service_id	Filtere die Liste nach der Leistung. Erlaubt sind eine einzelne ID sowie mehrere durch Komma getrennte IDs.
note	Freitextsuche in der Bemerkung. Um nach mehreren mit ODER verknüpften Kriterien zu filtern, gib den Parameter als note[] mehrfach an.
at	Datum des Zeiteintrages today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year oder Datum im Format YYYY-MM-DD
from,to	Zeiteinträge innerhalb der Zeitspanne – beide im gleichen Format wie at
billable	Ist der Zeiteintrag verrechenbar oder nicht? true oder false
locked	Ist der Zeiteintrag bereits abgeschlossen? true oder false
tracking	Läuft auf dem Zeiteintrag eine Stoppuhr? true oder false
sort	Erlaubt die Einträge sortiert auszugeben. Möglich sind date, user, customer, project, service, note, minutes und revenue. Default: date
direction	Die Richtung der Sortierung. Möglich sind asc oder desc. Default: hängt von sort ab: bei date, minutes und revenue ist es desc, sonst asc.
group_by	Erlaubt die Einträge gruppiert auszugeben. Details
limit	Mit dem Parameter limit ist es möglich, die maximale Anzahl der ausgegebenen Einträge zu begrenzen. Default: unbegrenzt
page	In Kombination mit dem Parameter limit können Folgeseiten ausgegeben werden. Default: 1

Antwort

Status: 200 OK

[
   {
      "time_entry": {...}
   },
   {
      "time_entry": {...}
   }
]

Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<time-entries type="array">
   <time-entry>
      ...
   </time-entry>
   <time-entry>
      ...
   </time-entry>
</time_entries>

Alle Zeiteinträge eines Tages auflisten

Listet alle Zeiteinträge des aktuellen Benutzers am heutigen Tag auf.

GET /daily.xml

GET /daily.json

Was einfach ein Alias für die längere Variante mit Parametern ist:

GET /time_entries.xml?user_id=current&at=today

GET /time_entries.json?user_id=current&at=today

Listet alle Zeiteinträge des aktuellen Benutzers am 7. Februar 2015 auf.

GET /daily/2015/2/7.xml

GET /daily/2015/2/7.json

Was wiederum das gleiche Ergebnis liefert wie:

GET /time_entries.xml?user_id=current&at=2015-02-07

GET /time_entries.json?user_id=current&at=2015-02-07

Zeiteinträge gruppieren

Mit dem Parameter group_by können Zeiteinträge gruppiert werden. Mögliche Gruppierungen sind user, customer, project, service, day, week, month und year.

Beispiel

GET /time_entries.xml?group_by=user

GET /time_entries.json?group_by=user

Antwort

Status: 200 OK

[
   {
      "time_entry_group": {
         "minutes": 10733,
         "revenue": 91568.333333333,
         "user_id": 26144,
         "user_name": "August Ausgedacht",
         "from": "2014-05-03",
         "to": "2014-09-23",
         "time_entries_params": {
            "user_id": 26144
         }
      }
   },
   {
      "time_entry_group": {
         "minutes": 57289,
         "revenue": 788439.3666668,
         "user_id": 246,
         "user_name": "Jette Jemand",
         "from": "2013-04-19",
         "to": "2015-08-19",
         "time_entries_params": {
            "user_id": 246
         }
      }
   }
]

Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<time-entry-groups type="array">
   <time-entry-group>
      <minutes type="integer">10733</minutes>
      <revenue type="float">91568.3333333334</revenue>
      <user-id type="integer">26144</user-id>
      <user-name>August Ausgedacht</user-name>
      <from type="date">2014-05-03</from>
      <to type="date">2014-09-23</to>
      <time-entries-params>
         <user-id>26144</user-id>
      </time-entries-params>
   </time-entry-group>
   <time-entry-group>
      <minutes type="integer">57289</minutes>
      <revenue type="float">788439.36666681</revenue>
      <user-id type="integer">246</user-id>
      <user-name>Jette Jemand</user-name>
      <from type="date">2013-04-19</from>
      <to type="date">2015-08-19</to>
      <time-entries-params>
         <user-id>246</user-id>
      </time-entries-params>
   </time-entry-group>
<time-entry-groups type="array">

Die Antwort enthält neben den Summen der Arbeitszeit und des Umsatzes die gemeinsamen Werte der Gruppe, beispielsweise die user_id und den user_name, wenn wie in unserem Beispiel nach dem Benutzer gruppiert wurde. Zusätzlich werden unter time_entries_params alle Parameter zum Aufruf der einzelnen Zeiteinträge der Gruppe aufgelistet.

Mehrere Werte können mit Komma getrennt miteinander kombiniert werden. Die Reihenfolge entscheidet dabei über die Sortierung der Ergebnisse.

Um beispielsweise die letzte Woche jedes Nutzers als Gruppe zu erhalten:

GET /time_entries.xml?group_by=user,week&at=last_week

GET /time_entries.json?group_by=user,week&at=last_week

Oder für die einzelnen Monate aller Projekte eines Kunden:

GET /time_entries.xml?group_by=project,month&customer_id=123

GET /time_entries.json?group_by=project,month&customer_id=123

Einzelnen Zeinteintrag anzeigen

Gibt einen einzelnen Zeiteintrag zurück. Dieser kann einem beliebigen Benutzer des Accounts gehören, solange der aktuelle Benutzer kein Zeiterfasser ist.

GET /time_entries/:id.xml

GET /time_entries/:id.json

Antwort

Status: 200 OK

{
   "time_entry": {
      "id": 36159117,
      "minutes": 15,
      "date_at": "2015-10-16",
      "note": "Feedback einarbeiten",
      "billable": true,
      "locked": false,
      "revenue": null,
      "hourly_rate": 0,
      "user_id": 211,
      "user_name": "Fridolin Frei",
      "project_id": 88309,
      "project_name": "API v2",
      "customer_id": 3213,
      "customer_name": "König",
      "service_id": 12984,
      "service_name": "Entwurf",
      "created_at": "2015-10-16T12:39:00+02:00",
      "updated_at": "2015-10-16T12:39:00+02:00"
   }
}

Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   <id type="integer">36159117</id>
   <date-at type="date">2015-10-16</date-at>
   <minutes type="integer">15</minutes>
   <revenue type="float" nil="true"></revenue>
   <hourly-rate type="integer">0</hourly-rate>
   <billable type="boolean">true</billable>
   <note></note>
   <user-id type="integer">211</user-id>
   <user-name>Fridolin Frei</user-name>
   <project-id type="integer">88309</project-id>
   <project-name>API v2</project-name>
   <service-id type="integer">12984</service-id>
   <service-name>Entwurf</service-name>
   <customer-id type="integer">3213</customer-id>
   <customer-name>König</customer-name>
   <locked type="boolean">false</locked>
   <created-at type="datetime">2015-10-16T12:39:00+02:00</created-at>
   <updated-at type="datetime">2015-10-16T12:39:00+02:00</updated-at>
</time-entry>

Läuft auf dem angeforderten Zeiteintrag die Stoppuhr, wird zusätzlich ausgegeben, seit wann diese läuft und wie viele Minuten akkumuliert auf dem Zeiteintrag gestoppt wurden (gemessene + bereits vorhandene Minuten).

Status: 200 OK

{
   "time_entry": {
      ...
      "tracking": {
         "since": "2015-10-16T12:44:17+02:00",
         "minutes": 12
      }
   }
}

Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   ...
   <tracking>
      <since type="datetime">2015-01-22T14:58:13+01:00</since>
      <minutes type="integer">12</minutes>
   </tracking>
</time-entry>

Einen Zeiteintrag erstellen

Erstellt einen neuen Zeiteintrag. Alle Attribute sind optional.

POST /time_entries.xml

POST /time_entries.json

Attribute

date_at	Datum des Zeiteintrages im Format YYYY-MM-DD. Default: Heute
minutes	Default: 0
note	Default: "" (leerer String)
user_id	Kann nur von Administratoren gesetzt werden. Default: ID des aktuellen Benutzers
project_id	Default: null (keinem Projekt zugeordnet)
service_id	Default: null (keiner Leistung zugeordnet)
locked	Kann nur von Administratoren gesetzt werden. Ein abgeschlossener Zeiteintrag kann nicht mehr bearbeitet oder gelöscht werden. Details false (Default) oder true

Anfrage

Content-Type: application/json

{
   "time_entry": {
      "date_at": "2015-9-15",
      "minutes": 185,
      "service_id": 243
   }
}

Content-Type: application/xml

<time-entry>
   <date-at>2015-9-12</date-at>
   <minutes>185</minutes>
   <service-id>243</service-id>
</time-entry>

Antwort

Status: 201 Created
Location: https://demo.mite.de/time_entries/52324.json

{
   "time_entry": {
      "id": 52324,
      "minutes": 185,
      "date_at": "2015-9-12",
      "note": "",
      "billable": true,
      "locked": false,
      "revenue": null,
      "hourly_rate": 0,
      "user_id": 211,
      "user_name": "Fridolin Frei",
      "project_id": null,
      "service_id": 243,
      "service_name": "Dokumentation",
      "created_at": "2015-09-13T18:54:45+02:00",
      "updated_at": "2015-09-13T18:54:45+02:00"
   }
}

Status: 201 Created
Location: https://demo.mite.de/time_entries/52324.xml

<?xml version="1.0" encoding="UTF-8"?>
<time-entry>
   <id type="integer">52324</id>
   <date-at type="date">2015-9-12</date-at>
   <minutes type="integer">185</minutes>
   <revenue type="float" nil="true"></revenue>
   <hourly-rate type="integer">0</hourly-rate>
   <billable type="boolean">true</billable>
   <note></note>
   <user-id type="integer">211</user-id>
   <user-name>Fridolin Fremd</user-name>
   <project-id type="integer" nil="true"/>
   <service-id type="integer">243</service-id>
   <service-name>Dokumentation</service-name>
   <locked type="boolean">false</locked>
   <created-at type="datetime">2015-09-13T18:54:45+02:00</created-at>
   <updated-at type="datetime">2015-09-13T18:54:45+02:00</updated-at>
</time-entry>

Einen Zeiteintrag bearbeiten

Aktualisiere einen Zeiteintrag mit den übergebenen Attributen. Nur Administratoren können auch Einträge anderer Benutzer bearbeiten; alle anderen nur die eigenen.

PATCH /time_entries/:id.xml

PATCH /time_entries/:id.json

Content-Type: application/json

{
   "time_entry": {
      "minutes": 120,
      "service_id": 3124
   }
}

Content-Type: application/xml

<time-entry>
   <minutes>120</minutes>
   <service-id>3124</service-id>
</time-entry>

Antwort

Status: 200 OK

{leer}

Einen Zeiteintrag löschen

Lösche einen Zeiteintrag:

DELETE /time_entries/:id.xml

DELETE /time_entries/:id.json

Antwort

Status: 200 OK

{leer}

Auch beim Löschen gilt: Nur Administratoren können auch Einträge anderer Benutzer löschen; alle anderen nur die eigenen. Der Versuch beispielsweise als Standard-Nutzer einen Zeiteintrag eines anderen Nutzers zu löschen gibt daher ein 404 Not Found zurück.

Abgeschlossene Zeiteinträge

Wenn ein Administrator das Attribut locked eines Zeiteintrages auf true gesetzt hat, gilt dieser als abgeschlossen und kann von niemandem mehr bearbeitet oder gelöscht werden. Der Versuch einen Eintrag dennoch zu ändern gibt folgenden Fehler zurück:

Status: 423 Locked

{
  "error": "Der Zeiteintrag wurde als abgeschlossen markiert und kann daher nicht bearbeitet werden."
}

Status: 423 Locked

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Der Zeiteintrag wurde als abgeschlossen markiert und kann daher nicht bearbeitet werden.</error>
</errors>}

Genauso beim Versuch einen abgeschlossenen Zeiteintrag zu löschen:

Status: 423 Locked

{
  "error": "Der Zeiteintrag wurde als abgeschlossen markiert und kann daher nicht gelöscht werden."
}

Status: 423 Locked

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Der Zeiteintrag wurde als abgeschlossen markiert und kann daher nicht gelöscht werden.</error>
</errors>}

Administratoren können dies mit dem Attribut force jedoch umgehen und damit beispielsweise locked wieder auf false setzen:

PATCH /time_entries/:id.xml

PATCH /time_entries/:id.json

Content-Type: application/json

{
   "time_entry": {
      "force": true,
      "locked": false
   }
}

Content-Type: application/xml

<time-entry>
   <force>true</force>
   <locked>false</locked>
</time-entry>

Antwort

Status: 200 OK

{leer}

Oder den Eintrag löschen:

DELETE /time_entries/:id.xml

DELETE /time_entries/:id.json

Content-Type: application/json

{
   "time_entry": {
      "force": true
   }
}

Content-Type: application/xml

<time-entry>
   <force>true</force>
</time-entry>

Antwort

Status: 200 OK

{leer}