Was von außen möglich ist

Kurzantwort: Pro Modell gibt es einen festen Satz Operationen — anlegen, lesen, ersetzen, teilweise ändern, löschen, suchen, dazu optional Dateien, Historie und Rollback. Welche davon Ihr Modell wirklich hat, entscheidet dessen Konfiguration; die verbindliche Auskunft gibt die OpenAPI-Beschreibung Ihrer Installation.

---

Der Operationskatalog

Alle Pfade beginnen mit der Basis-URL plus dem API-Pfad des Modells, etwa https://api.example.com/api/rest/crm/customer.

Was Sie tun wollen	Aufruf
Objekt anlegen	POST /create
Objekt mit Dateien anlegen	POST /create/upload (Multipart)
Objekt lesen, Felder selbst wählen	POST /read/{id}
Objekt schnell ansehen	GET /read/{id}
Objekt vollständig ersetzen	PUT /update/{id}
Einzelne Felder ändern	PATCH /update/{id}
Objekt löschen	DELETE /delete/{id}
Liste suchen, filtern, blättern	POST /query
Datei herunterladen	GET /{id}/file
Änderungshistorie lesen	POST /{id}/history
Auf eine Revision zurücksetzen	POST /{id}/rollback/{revision}

Die letzten drei sind optional und nur vorhanden, wenn das Modell sie freigibt.

Sonderfälle

Singletons — Modelle, von denen es genau ein Objekt pro Mandant oder Benutzer gibt (Einstellungen, Konfiguration). Ihnen fehlt die ID im Pfad: POST /read, PUT /update, PATCH /update, DELETE /delete. Ein zweites Anlegen scheitert mit object-already-exists|use-update.

Abstrakte Modelle — ein Oberbegriff mit mehreren konkreten Ausprägungen. Die Pfade sind dieselben, aber beim Schreiben müssen Sie den konkreten Typ angeben:

{ "data": { "@type": "crm.privatkunde", "name": "…" }, "response": ["+"] }

Beim Lesen und Löschen ist das nicht nötig — der Server ermittelt den Typ über die ID. In Antworten kommt er als @type zurück, sodass Sie im Client unterscheiden können.

Was es bewusst nicht gibt

Erwartung	Wirklichkeit
POST /save, das anlegt oder ändert	gibt es nicht — entscheiden Sie im Client anhand der id
Teilweises Lesen per Query-Parameter (?fields=)	die Feldauswahl steht im Körper, siehe Daten lesen
GET /query?filter=…	Suche läuft über POST /query mit strukturiertem Körper
Optimistic Locking über ETag oder version	nicht vorhanden — wer liest, ändert und zurückschreibt, kann fremde Änderungen überschreiben
Massenoperationen (mehrere Objekte in einem Request)	nicht vorgesehen; verschachteltes Schreiben deckt verwandte Objekte ab, siehe Verschachtelt schreiben
Ein Endpunkt, der alle Modelle auflistet	nein — die OpenAPI-Beschreibung ist die Übersicht

Warum POST zum Lesen?

Weil die Anfrage strukturierte Daten enthält: welche Felder Sie brauchen, wie tief Referenzen aufgelöst werden, welche Filter gelten, wie sortiert und geblättert wird. Das in eine URL zu pressen wäre unlesbar und stößt an Längengrenzen.

GET /read/{id} gibt es trotzdem — als Abkürzung, die immer alle Felder plus Referenz-IDs liefert. Gut zum Ausprobieren, ungeeignet für Produktion, weil Sie damit regelmäßig mehr Daten übertragen als nötig.

Welche Endpunkte Ihr Modell hat

Drei Wege, in dieser Reihenfolge:

1. OpenAPI-Beschreibung Ihrer Installation. Sie listet jeden vorhandenen Endpunkt samt Payload-Struktur. Der Pfad wird Ihnen genannt, üblich ist eine Swagger-Oberfläche unter der API-Basis.
2. Das Modell im Hub. Dort steht, welche Endpunkt-Arten aktiviert sind.
3. Ausprobieren. Ein nicht vorhandener Endpunkt antwortet mit 404, ein vorhandener ohne Berechtigung mit 403.

Was Sie nicht sehen

Der Server zeigt Ihnen nur, was Ihr Zugang sehen darf — und zwar auf drei Ebenen:

flowchart TB
    R["Ihr Request"] --> M{"Rolle für diese<br/>Operation vorhanden?"}
    M -->|nein| E["403"]
    M -->|ja| F["Feldrechte:<br/>nicht erlaubte Felder<br/>fehlen in der Antwort"]
    F --> Z["Zeilenfilter:<br/>eigener Mandant,<br/>eigene Objekte,<br/>Attributfilter"]
    Z --> D["Ihre Daten"]

Zwei Folgen für die Praxis:

• Ein Objekt, das Sie nicht sehen dürfen, ist 404, nicht 403. Der Server verrät nicht, dass es existiert.
• Ein Feld ohne Leserecht fehlt einfach in der Antwort. Rechnen Sie im Client damit, statt es vorauszusetzen.

Grenzen der Datenmenge

Grenze	Wert
Standard-Seitengröße	keine — limit ist standardmäßig -1, also unbegrenzt
limit: -1	liefert alles; nur für überschaubare Mengen sinnvoll
Dateidownload	wird vollständig in den Speicher gelesen, praktisch bis wenige hundert MB
Tiefe der Referenzauflösung	so tief, wie Sie sie anfordern — jede Ebene kostet Abfragen

Setzen Sie in Listen immer ein limit. Die Voreinstellung ist bequem zum Ausprobieren und gefährlich in Produktion.