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 Ressourcen­art, 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 &:

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

Der Bereich-Filter gilt auch für Datumsfelder, beide Grenztage gehören zum Ergebnis. So liest du alle Zeiten eines Mitarbeiters in einer Woche, von Montag bis Sonntag:

GET  https://app1.teamspace.de/api/time;depth=1?worker=54967&date=2026-09-07..2026-09-13

Eine Liste liefert standardmäßig höchstens 100 Einträge, size nennt die Gesamtzahl. Ist sie größer, holst du die nächsten Seiten mit ;offset=100, ;offset=200 und so weiter. Ob ein Filter einen Bereich erlaubt, zeigt server/api/<collection>/meta im Feld searchableRange. Den ganzen Ablauf rund um Zeitbuchungen zeigt Zeiten über die API anzeigen und buchen.

Matrix-Parameter im Detail

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

Mit ;depth=1 bleibt ein verknüpftes Objekt ein Link-Objekt. Die aufgelösten Felder stehen darin unter data. Das gilt auch für die Einträge einer Liste: /api/time;depth=1 liefert in items Link-Objekte, deren data die vollständige Buchung enthält.

Ein weiterer Matrix-Parameter ist evaluate. Er filtert nicht, sondern ergänzt jeden Eintrag der Liste um das Feld evaluation mit true oder false. /api/project;evaluate=isBookable liefert also alle Projekte und markiert die buchbaren. In einer Prüfung am 2026-09-10 waren das genau die Projekte, die auch der Filter ?isBookable=true liefert. Willst du nur buchbare Projekte, nimm den Filter. evaluate passt, wenn du alle Projekte zeigen und die nicht buchbaren nur kennzeichnen willst.

evaluate und depth stehen weder im API Compact Guide noch in der OpenAPI-Beschreibung.

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

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").

Gültige Werte über optionsUrl

Kommt der Wert eines Feldes aus einer Auswahlliste, trägt sein Link-Objekt eine optionsUrl. Sie zeigt auf die Liste der erlaubten Werte. An einer Zeitbuchung sieht das zum Beispiel so aus:

"area": {
  "caption": "Verrechenbar",
  "href": ".../api/timecategory/1201",
  "value": 1201,
  "optionsUrl": ".../api/timecategory?categoryType=2"
}

Für ein Objekt, das du erst anlegen willst, liefert server/api/<collection>/meta/template dieselben optionsUrl, bei Zeitbuchungen also server/api/time/meta/template. Übernimm die Adresse, statt sie selbst zusammenzubauen. Wie das beim Buchen von Zeiten aussieht, zeigt Zeiten über die API anzeigen und buchen.

Begriffe im Überblick

Häufige Probleme

Warum reagiert eine Abfrage mit depth so langsam? Der Matrix-Parameter depth löst verknüpfte Referenzen mit auf – je Generation kommt eine zusätzliche Auflösung hinzu. Schon ;depth=1 kann deutlich langsamer sein. Setze die Tiefe nur so hoch wie nötig, und folge im Zweifel lieber den href-Links der Antwort (HATEOAS), statt alles in einem Aufruf zu laden.

Warum liefert mein Filter mit Leerzeichen nichts oder einen Fehler? Werte mit Leerzeichen gehören in Anführungszeichen: ?name="bob ross". Ohne sie endet der Wert am Leerzeichen, und die Abfrage filtert auf das falsche Feld.

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).
• Welche Collections, Filter und Felder dein Server kennt, steht ab Version 26.2 in der OpenAPI-Beschreibung unter <server>/api/openapi.json. Die Filter-Operatoren und die Matrix-Parameter depth und evaluate stehen dort nicht, dafür gilt dieser Artikel.

Verwandte Themen

• Die OpenAPI-Beschreibung nutzen API Referenz

• Einführung in die API API Einführung

• Authentifizieren: Gerätepasswort & API-Token API Anleitung

• Kontakt über die API anlegen API Übungen