Login English

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

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.yo.lk/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.yo.lk/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}