Worum es geht
Für jedes Modell erzeugt der Generator einen REST-Controller mit einem festen Satz von Operationen. Alle Pfade beginnen mit /api/rest und dem API-Pfad des Modells. Der API-Pfad entsteht aus dem Ordner im Hub und dem Modellnamen in Kleinbuchstaben, zum Beispiel /crm/customer.
Der vollständige Satz
So sieht der Satz eines normalen Modells aus, wenn alles eingeschaltet ist. {basis} steht für /api/rest/crm/customer.
| Was du tun willst | Methode und Pfad | Körper |
|---|---|---|
| anlegen | POST {basis}/create | JSON |
| anlegen, mit Dateien | POST {basis}/create/upload | Multipart |
| lesen, Felder selbst wählen | POST {basis}/read/{id} | JSON mit response |
| lesen, schnell ansehen | GET {basis}/read/{id} | keiner, liefert immer * |
| ersetzen | PUT {basis}/update/{id} | JSON |
| ersetzen, mit Dateien | PUT {basis}/update/{id}/upload | Multipart |
| ändern | PATCH {basis}/update/{id} | JSON |
| ändern, mit Dateien | PATCH {basis}/update/{id}/upload | Multipart |
| löschen | DELETE {basis}/delete/{id} | keiner |
| suchen, filtern, blättern | POST {basis}/query | JSON mit response und parameter |
| Historie lesen | POST {basis}/{id}/history | JSON |
| auf alte Revision zurücksetzen | POST {basis}/{id}/rollback/{revision} | JSON mit response |
| Datei herunterladen | GET {basis}/{id}/file | keiner |
Die Endpunkt-Liste im Modell
Im Hub bekommt ein Modell eine Liste von Endpunkten. Jeder Eintrag hat einen Typ, und der Generator erzeugt daraus die Operationen:
| Typ in der Liste | Erzeugte Operationen |
|---|---|
| CREATE | POST /create (und /create/upload) |
| READ | POST /read/{id} und GET /read/{id}, keine Suche |
| LIST, QUERY oder SEARCH | POST /query |
| UPDATE | PUT /update/{id} und PATCH /update/{id} (jeweils auch /upload) |
| PATCH | nur PATCH /update/{id} |
| DELETE | DELETE /delete/{id} |
| HISTORY_READ, HISTORY_QUERY | POST /{id}/history, nur bei auditierten Modellen |
| HISTORY_ROLLBACK | POST /{id}/rollback/{revision}, nur bei auditierten Modellen |
| DOWNLOAD | GET /{id}/file, nur bei Datei-Modellen |
| UPLOAD | die /upload-Varianten, nur für Datei-Modelle von Bedeutung |
| unbekannter Typ | nichts; der Build meldet eine Warnung |
Dazu drei Regeln, die man leicht übersieht:
- create, read, update, patch, delete, query, upload und download werden erzeugt
- Historie und Rollback nicht, die muss man ausdrücklich eintragen
- READ erzeugt nur das Lesen per
id - Wer eine Liste braucht, trägt LIST (oder QUERY) ein
- ohne
auditingim Modell entstehen keine History- und Rollback-Endpunkte, egal was in der Liste steht
Jeder Eintrag der Liste kann außerdem sagen, wer den Endpunkt nutzen darf: eine eigene Rolle, die Grundrolle des Modells oder öffentlich ohne Anmeldung. Das steht unter Modellrollen.
Die Sonderformen
Wann: der Regelfall
Der vollständige Satz wie oben, gefiltert durch die Endpunkt-Liste. Jedes Objekt wird über seine id im Pfad angesprochen.
Wann: Das Modell ist als Singleton markiert: genau ein Objekt pro Scope.
Die Pfade haben keine id, der Server findet das eine Objekt selbst: POST /create, POST /read, GET /read, PUT /update, PATCH /update, DELETE /delete, GET /file, POST /history, POST /rollback/{revision}. Eine Suche gibt es nicht. Ein zweites create scheitert mit 400 object-already-exists|use-update, ein update ohne vorhandenes Objekt mit 404 no-data-exists|use-create. Siehe Singletons.
Wann: Das Modell hat Untertypen, z. B. kunde mit privatkunde und firmenkunde.
Das Modell bekommt eine Hub-API mit denselben Pfaden. Sie leitet jede Anfrage an die API des konkreten Untertyps weiter: beim Schreiben anhand von @type im Payload, beim Lesen und Löschen anhand des Typs, der zur id gespeichert ist. Siehe Abstrakte Modelle.
Wann: Das Modell speichert eine Datei.
Zusätzlich gibt es GET /{id}/file zum Herunterladen, sobald DOWNLOAD oder READ eingetragen ist. Die /upload-Varianten gibt es, sobald UPLOAD, CREATE oder UPDATE eingetragen ist: Ein Datei-Modell, das keine Datei annehmen kann, wäre nutzlos. Siehe Dateien.
Welche Endpunkte hat mein Modell?
-
1ClientOpenAPI-Beschreibung der Installation öffnen. Sie listet jeden erzeugten Endpunkt mit seinem PayloadSie ist die verbindliche Auskunft, weil sie aus dem erzeugten Code entsteht.
-
2AdminModell im Hub ansehen: Welche Typen stehen in der Endpunkt-Liste? Ist das Modell auditiert, ein Singleton, abstrakt, ein Datei-Modell?
-
3ClientAusprobieren: Die Antwort verrät, woran es liegtErgebnis: 404 → Endpunkt gibt es nicht. 403 → Endpunkt gibt es, die Rolle fehlt. 401 → Token fehlt oder ist abgelaufen.
Was es bewusst nicht gibt
| Erwartung | So ist es |
|---|---|
POST /save, das je nach id anlegt oder ändert | gibt es nicht; der Client entscheidet anhand der id zwischen create und update |
Feldauswahl per Query-Parameter (?fields=) | die Feldauswahl steht im Körper, siehe Feldauswahl |
Suche per GET mit Parametern in der URL | Suche läuft über POST /query |
| Massenoperationen für viele Objekte in einem Request | nicht vorgesehen; verwandte Objekte lassen sich verschachtelt schreiben |
| ein Endpunkt, der alle Modelle auflistet | die OpenAPI-Beschreibung ist diese Übersicht |