• Einführung
• Ablauf
• Beispiel
• Einschränkungen

Einführung

Über die Änderungs-Endpunkte können Änderungen, die zu einem früheren Zeitpunkt an bereits empfangenen Ressourcen vorgenommen wurden, abgefragt werden. So entfällt das wiederholte und aufwendige Übertragen aller Daten; Dies ist vor allem dann praktisch, wenn ein lokaler Datenspeicher mit den Daten bei mite synchron gehalten werden soll.

Die Änderungs-Endpunkte sind für Zeiteinträge, Kunden, Projekte und Leistungen verfügbar.

Bitte beachten: Änderungen können nicht von Zeiterfasser ausgelesen werden.

Ablauf

Bei GET-Requests auf /time_entries.jsonxml, /customers.jsonxml, /projects.jsonxml und /services.jsonxml wird ein Response-Header namens »X-Changes-Link« mit ausgegeben. Dieser enthält die URL, auf der ein GET-Request ausgeführt werden kann, um alle Änderungen seit dem Empfang der ursprünglichen Liste zu erhalten.

Die Antwort des GET-Requests auf den Changes-Link enthält dann wiederum einen neuen Changes-Link im Header »X-Changes-Link«. So können fortlaufend alle Änderungen empfangen werden.

Beispiel

Das folgende Beispiel enthält ein in der Zwischenzeit geändertes Projekt (»updated«), ein neu erstelltes Projekt (»created«) und ein gelöschtes Projekt (»deleted«). Bei den beiden ersten Fällen enthält das Attribut »record« die komplette erstellte oder geänderte Ressource:

GET /projects/changes/{token}.xml

GET /projects/changes/{token}.json

[
  {
    "change": {
      "record_type": "project",
      "action": "updated",
      "record_id": 1322027,
      "record": {
        "project": {...}
      }
    }
  },
  {
    "change": {
      "record_type": "project",
      "action": "created",
      "record_id": 1322030,
      "record": {
        "project": {...}
      }
    }
  },
  {
    "change": {
      "record_type": "project",
      "action": "deleted",
      "record_id": 1317020,
      "record": null
    }
  }
]

<?xml version="1.0"?>
<changes type="array">
   <change>
      <record-type>project</record-type>
      <record-id>1322027</record-id>
      <action>updated</action>
      <record>
         <project>...</project>
      </record>
   </change>
   <change>
      <record-type>project</record-type>
      <record-id>1322030</record-id>
      <action>created</action>
      <record>
         <project>...</project>
      </record>
   </change>
   <change>
      <record-type>project</record-type>
      <record-id>1317020</record-id>
      <action>deleted</action>
      <record/>
   </change>
</changes>

Einschränkungen

1. Änderungen können nicht mit Filtern und/oder Gruppierungen kombiniert werden; Es werden immer alle geänderten Ressourcen des entsprechenden Typs ausgegeben. Es muss daher gegebenenfalls clientseitig manuell gefiltert werden.
2. Änderungen enthalten keine Einträge, deren Subressourcen geändert wurden. Dies betrifft die Attribute customer_name bei Projekten und customer_name, project_name und service_name bei Zeiteinträgen. Um diese Attribute ebenfalls aktuell zu halten, müssen zusätzlich die Changes-Links der entsprechenden Subressourcen abgefragt werden.
3. Änderungen können nur innerhalb von sieben Tagen ausgelesen werden. Danach wird eine Fehlermeldung ausgegeben.
4. Im Zweifelsfall werden zu viele Änderungen mit ausgegeben. Es sollte daher beispielsweise der Fall berücksichtigt werden, dass auf dem Client nicht mehr vorhandene Ressourcen in der Antwort als deleted aufgeführt werden oder als created markierte bereits vorhanden sind.