Zum Hauptinhalt springen
Hilfecenter

Die OpenAPI-Beschreibung nutzen

Ab Version 26.2 beschreibt jeder Server seine REST-API maschinenlesbar unter <server>/api/openapi.json. Wo die Beschreibung liegt, was drinsteht, was fehlt und worauf du bei Server-Adresse und eigenen Feldern achtest.

Ab Version 26.2 liefert jeder teamspace-Server eine Beschreibung seiner REST-API im Format OpenAPI. Sie listet alle Adressen mit ihren Methoden, die Filter jeder Liste und die Felder jedes Objekts. Wer eine Anwendung baut oder einen Coding-Agenten damit beauftragt, schlägt dort nach, statt Feldnamen zu raten.

Wo die Beschreibung liegt

Die Beschreibung und zwei Ansichten dafür liegen unter deiner Server-Adresse:

<server>/api/openapi.json           Beschreibung als JSON (OpenAPI 3.0.1)
<server>/htdocs/openapi-docs.html   Ansicht mit Swagger
<server>/htdocs/api-docs.html       Ansicht mit RapiDoc

Alle drei sind ohne Anmeldung lesbar. Die Daten selbst bleiben geschützt: Wer <server>/api/time ohne Zugangsdaten aufruft, bekommt 401.

Die beiden Ansichten zeigen denselben Inhalt zum Durchklicken. Für Programme und Coding-Agenten ist die JSON-Datei die richtige Quelle. Welche Version dein Server hat, steht darin unter info.version, zum Beispiel 2026.2.85.

Welche Server-Adresse gilt

<server> ist die Adresse, unter der du teamspace im Browser öffnest, zum Beispiel https://app1.teamspace.de. An diese Adresse hängst du /api/… an.

⚠ Achtung: Übernimm die Angabe servers aus der Datei nicht ungeprüft. Bei einer Stichprobe am 2026-09-10 zeigte sie auf einem Server auf die Website statt auf den Server selbst. Verwende immer die Adresse, die der Benutzer eingibt.

Nach der Anmeldung nennt die Geräte-Ressource im Feld apiHost die Basis-Adresse der API. Wie du sie abrufst, zeigt Authentifizieren: Gerätepasswort & API-Token.

Was in der Beschreibung steht

  • Pfade und Methoden: jede Collection mit Liste (GET /api/time), Anlegen (POST /api/time) und dem einzelnen Element (GET, PUT, DELETE auf /api/time/{id}). Nicht jede Collection kennt alle Methoden, timecategory zum Beispiel nur GET.
  • Filter: die Query-Parameter jeder Liste. Für /api/time sind das unter anderem date, worker und project, für /api/project unter anderem isBookable, isActive, isTemplate, isDraft und customer.
  • Matrix-Parameter: sort, limit (Standard 100), offset und parent. Bei sort nennt die Beschreibung je Liste die Felder, nach denen du sortieren kannst.
  • Schemas: die Felder jedes Objekts mit Typ und kurzer englischer Erklärung. Für Anlegen und Ändern gibt es ein eigenes Schema mit der Endung Input, zum Beispiel TimeInput.
  • Anmeldung: HTTP Basic Auth. Das Schema Device sagt dazu: Benutzername ist die Geräte-ID, Passwort der Token.

So steht ein Feld im Schema Time:

"amount": {
  "type": "integer",
  "format": "int32",
  "description": "in minutes"
}

Verknüpfte Felder wie project oder worker führt die Beschreibung als ApiValuedLink. In der Antwort kommen sie als Link-Objekt mit caption, href und value. Beim Schreiben genügt der value, wie in Aufbau der API-Adressen (URL-Struktur) unter HATEOAS erklärt.

Eigene Felder deines Mandanten

Richtet ein Mandant eigene Felder ein, erscheinen sie in der Beschreibung als zusätzliche Filter an den Listen. Im Schema des Objekts stehen sie nicht als eigenes Feld. Ihre Namen sind auf jedem Server andere.

Für eine Anwendung heißt das: Verlass dich nur auf die Standardfelder. Sie sind bei gleicher Version auf allen Servern gleich. Ein eigener Filter, den du auf einem Server findest, fehlt auf dem nächsten.

Was die Beschreibung nicht enthält

  • Pflichtfelder: Nur wenige Schemas nennen sie, zum Beispiel Contact mit lastname. Die Zeitbuchung nennt keine. Dass nichts markiert ist, heißt aber nicht, dass nichts Pflicht ist: Eine Zeitbuchung ohne date, project, area und field lehnt der Server ab, und ein Beleg braucht immer die Belegart. Die Pflichtfelder der Belege stehen in der Feldreferenz: Spesen- und Belegfelder, der Stand zur Zeitbuchung in Zeiten über die API anzeigen und buchen.
  • depth und evaluate: Beide Matrix-Parameter kommen in der Beschreibung nicht vor. depth löst verknüpfte Objekte auf. Was über evaluate bekannt ist, steht in der URL-Struktur.
  • Filter-Operatoren: „enthält“ (*=), Bereiche (von..bis), mehrere Werte und leere Felder. Auch diese Schreibweisen erklärt die URL-Struktur.
  • Fehlerantworten: Meist ist nur der Erfolgsfall beschrieben, POST /api/time etwa nur mit 201. Ohne gültige Anmeldung antwortet der Server mit 401 und reinem Text. Andere Fehler kommen als JSON mit den Feldern message und stacktrace, eine abgelehnte Zeitbuchung zum Beispiel als 403 mit den fehlenden Feldern in message.
  • Namen aus der Oberfläche: Die Beschreibung ist englisch und spricht von Collections. Das Modul „Offene Punkte“ ist zum Beispiel die Collection issue, nicht ticket.

Weitere Quellen auf dem Server

  • <server>/api/api: die Liste aller Collections, ohne Anmeldung lesbar.
  • <server>/api/<collection>/meta: nur mit Anmeldung, ohne antwortet der Server mit 500. Nennt die erlaubten Methoden für Liste und Element, alle Filter mit Typ und ob sie sortierbar sind oder einen Bereich von..bis erlauben (searchableRange), teils mit deutscher Beschreibung.
  • <server>/api/<collection>/meta/template: die Vorlage für ein neues Objekt, ebenfalls mit Anmeldung. An Auswahlfeldern steht dort die optionsUrl mit den gültigen Werten, bei der Zeitbuchung etwa für area und field.
  • <server>/api/api/dto.ts: die Objekte als TypeScript-Klassen, teils mit Kommentaren. Dort steht zum Beispiel, dass ein Link-Objekt immer einen value braucht.
  • API-Explorer: die ältere Browser-App zum Erkunden der API. Wo du sie findest, steht in der Einführung in die API.

Typische Fragen & Anforderungen

Du möchtest …So geht’s
alle Filter einer Liste sehenIn openapi.json unter paths → /api/<collection> → get → parameters nachsehen oder die Liste in der Swagger-Ansicht aufklappen.
wissen, welche Felder du beim Anlegen schicken kannstDas Schema mit der Endung Input lesen, z. B. TimeInput für POST /api/time.
die Version deines Servers prüfen<server>/api/openapi.json öffnen, Feld info.version.
einem Coding-Agenten die API erklären<server>/api/openapi.json und das Thema API im Hilfecenter als Quelle nennen. Die Server-Adresse gibst du selbst vor, statt sie aus servers übernehmen zu lassen.

Häufige Probleme

Warum landen die Anfragen meiner Anwendung auf einer falschen Adresse? Prüf, ob sie die Adresse aus servers übernommen hat. Diese Angabe kann von der Adresse abweichen, unter der du teamspace öffnest. Lass die Server-Adresse den Benutzer eingeben.

Warum steht in der Beschreibung ein Filter, den ich nirgends erklärt finde? Wahrscheinlich ist es ein eigenes Feld eines Mandanten auf diesem Server. Solche Filter stehen nicht im Schema des Objekts und fehlen auf anderen Servern. Bau deine Anwendung nicht darauf auf.

Verwandte Themen