Aufbau der API-Adressen (URL-Struktur)

Jede Ressource der teamspace-API wird über eine URL angesprochen. Wenn du den Aufbau dieser Adressen einmal verstanden hast, kannst du dir die meisten Anfragen selbst herleiten – das Muster ist überall gleich.

Die fünf Bestandteile einer API-Adresse

Eine typische API-Adresse setzt sich aus diesen Teilen zusammen:

server/api/collection;matrixparameter?query

server – die Adresse deiner teamspace-Installation, z. B. https://app1.teamspace.de.
api – alles, was zur API gehört, liegt unter dem festen Pfadsegment api.
collection – die Ressourcenart, die du ansprichst, z. B. project, time, contact, expense.
matrixparameter – optionale Schalter direkt am Pfad, mit Semikolon getrennt (z. B. die Ergebnismenge begrenzen oder sortieren).
query – das klassische Abfrage-Anhängsel hinter ?, um die Collection zu filtern (z. B. ?name=alice&date=2000-01-01).

Collection ansprechen

Sprichst du eine ganze Collection an, listet die API deren Elemente auf. Über Matrix-Parameter und Query steuerst du Umfang und Filter:

server/api/collection;matrixparameter?query
https://app1.teamspace.de/api/time;limit=10;sort=project?date=2022-01-31

Dieses Beispiel liest aus der Collection time die ersten 10 Einträge (limit=10), sortiert nach Projekt (sort=project) und gefiltert auf das Datum 2022-01-31.

Einzelnes Element ansprechen

Ein einzelnes Element erreichst du, indem du an die Collection die Element-ID anhängst:

server/api/collection/itemid;matrixparameter
https://app1.teamspace.de/api/time/123;depth=0

Hier wird das Zeit-Element mit der ID 123 ausgelesen. Der Matrix-Parameter depth=0 steuert, wie tief verschachtelte/verknüpfte Objekte mitgeliefert werden.

Antwort einer Collection

Fragst du eine Collection ab, antwortet die API mit einem Objekt, das die Treffer als items enthält – samt Angaben zur Gesamtzahl und Seitengröße:

{
  "size": 3,
  "offset": 0,
  "limit": 100,
  "items": [
    { "caption": "Example corp.", "href": ".../api/contact/3456", "value": 3456 }
  ]
}

Jedes Element ist ein Link-Objekt mit caption, href und value (der ID). Über href lädst du das vollständige Element nach – du musst dir die URL nicht selbst zusammenbauen (HATEOAS, siehe unten).

Sammlungen filtern (Query)

Den Query-Teil hinter ? nutzt du, um eine Collection zu filtern. Mehrere Bedingungen verknüpfst du mit &:

Filter	Schreibweise	Beispiel
Gleich (`=`, ohne Groß-/Kleinschreibung)	`?field=value`	`?name="bob ross"&car=volvo&age=3`
Enthält	`?field*=val`	`?name*="bo"`
Bereich	`?field=1..3`	`?age=20..30`
Oder (mehrere Werte)	`?field=A,B,C`	`?name=alice,"bob ross",charlie`
Feld nicht leer	`?field`	`?name=bob&car`
Feld leer	`?!field`	`?name=bob&!car`

Bei Werten mit Leerzeichen setzt du Anführungszeichen ("bob ross"). Beispiel: alle Kontakte, deren Bezeichnung „examp” enthält:

GET  https://app1.teamspace.de/api/contact?caption*=examp

Matrix-Parameter im Detail

Matrix-Parameter stehen am Pfad (;-getrennt) und steuern Umfang und Form der Antwort:

Zweck	Schreibweise	Wirkung
Aufsteigend sortieren	`;sort=name`	nach Feld `name` aufsteigend
Absteigend sortieren	`;sort=!name`	nach Feld `name` absteigend
Ergebnismenge	`;limit=100`	erste 100 Treffer
Versatz	`;offset=200`	erste 200 Treffer überspringen
Teilbaum	`;parent=1234`	Kinder des Elements 1234 (nur Baumstrukturen)
Verschachtelungstiefe	`;depth=1`	erste Generation verknüpfter Referenzen auflösen (kann langsam sein)
Hinweise anzeigen	`;showhints=true`	verfügbare Sortierungen einblenden

Für einzelne Elemente gibt es zusätzlich einen Caching-Parameter:

Zweck	Schreibweise	Wirkung
Caching (7 Tage)	`;lck=value`	Antwort mit 7-Tage-Caching-Header; `value` ist eine Versionskennung. Solange sie sich nicht ändert, nutzt der HTTP-Client seinen Cache. Tipp: das `_lastModifiedDate` aus der Collection als Version verwenden.

HATEOAS: verknüpfte Ressourcen

Verweist ein Element auf ein anderes (z. B. ein Kontakt auf seine Adresse), liefert die API ein Link-Objekt statt einer bloßen ID:

"mainAddress": {
  "caption": ";;Examplestreet 7;Examplecity;;122456;Deutschland",
  "href": ".../api/contactfield/173880993",
  "rel": "contactfield",
  "value": 173880993
}

So folgst du der Kette: vom Kontakt zur Adresse, von dort weiter. Beim Aktualisieren zählt nur der value – du musst das ganze Link-Objekt nicht zurückschicken (statt subtype: {…} genügt z. B. subtype: "HOME").

Begriffe im Überblick

Begriff	Bedeutung	Beispiel
server	Adresse der Installation	`https://app1.teamspace.de`
collection	Ressourcenart	`time`, `project`, `contact`
id	ID eines konkreten Elements	`123`
Matrix-Parameter	Optionen am Pfad (`;`-getrennt)	`limit=10`, `sort=project`, `depth=0`
Query	Filter hinter `?`	`?date=2022-01-31`

Hinweise

Die Collection richtet sich nach dem fachlichen Bereich – die Namen entsprechen den teamspace-Objekten (z. B. contact für Kontakte, expense für Belege).
Matrix-Parameter stehen am Pfad und werden mit Semikolon getrennt; die Query steht ganz am Ende hinter ?. Beides lässt sich kombinieren.
Konkrete Request- und Response-Beispiele je Ressource liefert der API Compact Guide (PDF & PowerPoint zum Download).