RESTful Webservices

Ab Version 5.0 unterstützt todo4teams Webservices im REST-Format. REST bedeutet Representational State Transfer, siehe hier für eine Einführung.

Über diese Schnittstelle können externe Anwendungen Tickets abrufen, suchen, erzeugen und ändern.

Die todo4teams RESTful Services unterstützen dabei die Datenformate XML und JSON sowie (für einige Services) HTML. Über das zu verwendende Datenformat entscheidet der Client durch setzen der HTTP-Header-Attribute Accept (beim Abruf von Daten) und Content-Type (wenn Daten gesendet werden).

Zum Testen der einzelnen Services können Sie die Programme curl oder wget verwenden. In den folgenden Abschnitten werden die Aufrufe beispielhaft mit curl gezeigt.

todo4teams beschränkt den Zugriff auf die Services durch einen IP-Filter. Das bedeutet, dass nur Clients mit bekannten IP-Adressen die genannten URLs abrufen können. Sie konfigurieren die Liste erlaubter Client-Systeme mit ihren IP-Adressen, indem Sie sich mit der Rolle Admin oder Superadmin in todo4teams anmelden und den Reiter Systeme auswählen.

Zusätzlich kann eine Authentifizierung per HTTPAUTH BASIC erzwungen werden, Details siehe hier.

Beim Zugriff auf REST-URLs ist es wichtig, dass Sie für jede Aktion (Abrufen, Erzeugen, Ändern, Löschen) die passende HTTP-Methode GET, POST, PUT oder DELETE verwenden. In den Beispielen wird die HTTP-Methode dem curl-Befehlt mit dem Parameter X übergeben. Die REST-Client-Implementierungen stellen jeweils eigene Methoden je HTTP-Methode zur Verfügung.

Erzeugen neuer Tickets per REST

Um per REST ein neues Ticket zu erzeugen, senden Sie einen HTTP POST-Request mit nachfolgendem Inhalt an die URL http://yourtodoserver/ToDoServer/rest/tasks:

{
"addressedGroupId":17,
"attachments":[{"content":"am9v","filename":"attachment.txt"}],
"description":"This is my first todo",
"minutes":60,
"ownerId":7,
"priority":0,
"title":"First"
}

Dieser JSON-Code erzeugt ein neues Ticket mit dem Titel "First", der Beschreibung "This is my first todo", einer Zielzeit von 60 Minuten an die Gruppe mit der ID 17 und dem Besitzer mit der ID 7. Es wird außerdem eine Datei mit dem Namen attachment.txt an das neue Ticket angehängt.

Als Ergebnis der Aktion wird die ID des neuen Tickets zurückgeliefert.

Testen Sie den Service, indem Sie den JSON-Code in eine Datei ticket.json speichern und folgendes Kommando aufrufen:

cat ticket.json|  curl -H "Content-Type: application/json" -X POST --data-binary @- "http://yourtodoserver/ToDoServer/rest/tasks"

Beachten Sie bitte, dass der Dateiinhalt (im Attribut "content") Base64-kodiert übergeben werden muss. 

Das folgende Beispiel fügt dem Ticket automatisch zwei Formulare hinzu und setzt einige Feldwerte. Beachten Sie, dass die Formular-IDs mit Formular-Vorlagen in Ihrem System übereinstimmen müssen:

{
"addressedGroupId":17,
"description":"This is my first todo",
"forms":[
 {
"id":41,
"fields":
  {"Straße_t":"",
 "Name":"Meier",
 "Vorname":"Max",
  }
 },
 {
"id":42,
"fields":{
   "DeviceID" : "54354325435"
  }
 }
],
"minutes":480,
"ownerId":7,
"priority":0,
"title":"The title!"
}

Die Zielzeit wird hier, ebenso wie beim Ändern von Tickets per REST-Aufruf, mit dem Element minutes in Minuten angegeben.

Wenn Sie statt JSON das XML-Format bevorzugen, verwenden Sie das folgende Beispiel als Vorlage, um ein Ticket zu erzeugen:

In diesem Beispiel wird ein Dateianhang erzeugt und ein Formular angehängt.


<task>
<addressedGroupId>17</addressedGroupId>
<attachments>
 <attachment>
  <content>am9v</content>
  <filename>jee3</filename>
 </attachment>
</attachments>
<description>This is my first todo</description>
<forms>
 <form>
  <id>41</id>
  <fields>
   <entry>
    <key>Name_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Meier</value>
   </entry>
  </fields>
 </form>
</forms>
<minutes>300</minutes>
<ownerId>7</ownerId>
<priority>0</priority>
<title>The XML Title</title>
</task>

Benutzen Sie dann zum Testen den folgenden Befehl, wobei der XML-Code in der Datei ticket.xml gespeichert wäre:

cat ticket.xml|  curl -H "Content-Type: application/xml" -X POST --data-binary @- "http://yourtodoserver/ToDoServer/rest/tasks"

Wie Sie Formularattribute wie Fließkommazahlen, Kalendardaten etc. senden können, lesen Sie bitte hier.  

Abruf der Benutzer- und Gruppenliste

Sie können die Listen aller Benutzer und Gruppen Ihrer todo4teams-Instanz per REST abrufen. Rufen Sie dazu die URL http://yourtodoserver/ToDoServer/rest/users bzw. http://yourtodoserver/ToDoServer/rest/workgroups entweder mit dem Accept-Type application/xml oder application/json ab, wie in diesen Beispielen:

Abruf der Benutzerliste
curl  -H "Accept: application/xml" -H "Content-Type: application/xml" -X GET   "http://yourtodoserver/ToDoServer/rest/users"

curl  -H "Accept: application/json" -H "Content-Type: application/json" -X GET   "http://yourtodoserver/ToDoServer/rest/users"
Abruf der Gruppenliste
curl  -H "Accept: application/xml" -H "Content-Type: application/xml" -X GET   "http://localhost:8080/ToDoServer/rest/workgroups"

curl  -H "Accept: application/json" -H "Content-Type: application/json" -X GET   "http://localhost:8080/ToDoServer/rest/workgroups"

Abruf einzelner Tickets

Um einzelne Tickets per REST abzurufen, lesen Sie die URL der Form http://yourtodoserver/ToDoServer/rest/tasks/<ticketid> aus, z.B. http://yourtodoserver/ToDoServer/rest/tasks/14515 mit einem GET-Request auf.

Diesen Aufruf können Sie auch im Browser testen, das Ticket wird dann im HTML-Format angezeigt.

Im XML-Format könnte ein Abruf so aussehen:

curl -o out.xml -H "Accept: application/xml" -X GET   "http://yourtodoserver/ToDoServer/rest/tasks/14515"

Das Ergebnis könnte im XML-format wie folgt aussehen:


<task>
<addressedGroupId>17</addressedGroupId>
<attachments>
 <attachment>
  <content>am9v</content>
  <filename>jee3</filename>
 </attachment>
</attachments>
<creationDate>2015-01-29 14:46</creationDate>
<description>This is my first todo</description>
<forms>
 <form>
  <fields>
   <entry>
    <key>Straße_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>Name_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Meier</value>
   </entry>
   <entry>
    <key>Telefon_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>Ort_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>PLZ_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
  </fields>
  <id>41</id>
  <name>Kunde mobil</name>
 </form>
 <form>
  <fields>
   <entry>
    <key>t10</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">654645654325329</value>
   </entry>
   <entry>
    <key>t12</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>t13</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>4HKFT_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>5HKBez_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
   <entry>
    <key>K_ 5HKL_t</key>
    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string"></value>
   </entry>
  </fields>
  <id>42</id>
  <name>Projekterfassung Öl-Brennwert</name>
 </form>
</forms>
<id>14515</id>
<minutes>-843</minutes>
<ownerId>7</ownerId>
<priority>0</priority>
<properties/>
<scheduledEndDate>2015-01-29 23:54</scheduledEndDate>
<status>0</status>
<title> Yeah!</title>
</task>

Die so geladene Ticket-Repräsentation können sie bearbeiten und damit das bestehende Ticket auf dem Server aktualisieren - wie im nächsten Abschnitt gezeigt wird.

Änderung von Tickets

Um den Zustand eines Tickets auf dem Server zu aktualisieren, senden Sie veränderte XML oder JSON-Repräsentation per PUT-Request an die URL des Tickets, z.B.  http://yourtodoserver/ToDoServer/rest/tasks/14515. Achten Sie darauf, den passenden Content-Type im Aufruf zu verwenden, wie in diesen Beispielen:

Update des Ticket 14519 mit dem in ticket.json im JSON-Format gespeicherten Zustand:

cat ticket.json|  curl -H "Content-Type: application/json" -X PUT --data-binary @- "http://yourtodoserver/ToDoServer/rest/tasks/14519"

Update des Ticket 14519 mit dem in ticket.xml im XML-Format gespeicherten Zustand:

cat ticket.xml|  curl -H "Content-Type: application/xml" -X PUT --data-binary @- "http://yourtodoserver/ToDoServer/rest/tasks/14519" 

Bitte beachten Sie:

  • Um die Zielzeit eines Tickets zu verändern, benutzen Sie das Element minutes. Änderungen der Elemente creationDate, startDate, endDate und scheduledEndDate werden nicht übernommen.
  • Sie können Tickets nur ändern, solange sie sich im Zustand offen befinden. 
  • Formulare und Dateianhänge werden so übernommen, wie per REST gesendet: Wenn Sie also einen Dateianhang in der REST-Repräsentation löschen und das Ticket aktualisieren, wird der Anhang auch auf dem Server vom Ticket entfernt. Gleiches gilt für Formulare.

Löschen von Tickets per REST-Aufruf

Sie können Tickets durch einen HTTP-DELETE-Request an die URL des Tickets löschen. Beispiel:

curl -i -H "Accept: application/json" -X DELETE "http://yourtodoserver/ToDoServer/rest/tasks/14517"

Tickets suchen - Archivabfragen per REST

Sie können flexibel per REST nach bestimmten Tickets suchen, indem Sie suchanfragen an die URL http://localhost:8080/ToDoServer/rest/query?q=... senden. Sie erhalten dann eine Liste von Ticketrepräsentationen als JSON- oder XML-Daten als Ergebnis.

Der HTTP-Parameter q enthält dabei das Suchmuster in Form eines SQL-Where-Ausdrucks. Beachten Sie bitte, dass Sie diesen Parameter URL-kodiert einsetzen müssen.

Wenn Sie z.B. nach Tickets suchen möchten, die im Titel das Wort Meier enthalten und deren id größer als 14000 ist, sähe die Query so aus: task.id>14000 and task.title like '%Meier%'

URL-kodiert ergibt sich  das task.id%3E14000+and+task.title+like+%27%25Meier%25%27 als Parameter q und folgenden Aufruf:

curl  -H "Accept: application/json" -H "Content-Type: application/json" -X GET   "http://yourtodoserver/ToDoServer/rest/query?q=task.id%3E14000+and+task.title+like+%27%25Meier%25%27&limit=1000&withAttachments=true"

Mit dem optionalen Parameter limit geben Sie eine maximale Anzahl Ergebnisse an. Mit dem Parameter withAttachments=true unterdrücken Sie die Attachment-Elemente. Die Verwendung von withAttachments=true ist besonders dann empfehlenswert, wenn viele Tickets abgerufen werden, da sonst die Datenmenge leicht mehrer hundert Megabyte überschreitet.

     

Schnelleinstieg

Unterseiten