Routen & CRUD
Die Routen sind die Einstiegspunkte Ihrer API. Sie sind nach Ressource gruppiert, und Sie können sie von Hand schreiben oder aus einem Modell generieren.
Eine Route definieren
Section titled “Eine Route definieren”Eine Route trägt eine Methode, einen Pfad, Parameter und
Antworten. Der Pfad verwendet die Syntax {{param}} von Restorm: sobald Sie
{{id}} in den Pfad eingeben, erscheint der entsprechende Parameter; entfernen
Sie ihn, wird er gelöscht.
Die Parameter
Section titled “Die Parameter”Die Registerkarte Definition einer Route listet ihre Parameter auf — die
Pfad-Parameter (aus den Platzhaltern {{param}} erstellt) und die
Query-/Header-Parameter, die Sie mit Parameter hinzufügen ergänzen. Jeder
trägt einen Namen, einen Ort (in), seine Erforderlichkeit, eine
Beschreibung und optional ein Beispiel.
Die Zelle Typ ist eine Combo: Wählen Sie mit einem einzigen Klick ein
Primitiv (string, integer, number, boolean) oder einen der benannten
Enums des Designs. Für die reichhaltigeren Fälle wählen Sie Advanced…, um
ein kleines Fenster zu öffnen, in dem Sie:
- den Parameter zu einem Array machen und seinen Elementtyp wählen können
(
array<string>, …) — ein mehrwertiger Query-Parameter; - ihm Inline-Enum-Werte geben können (die erlaubte Menge, als Chips aufgelistet), wenn er nicht durch einen benannten Enum typisiert ist;
- In einen benannten Enum extrahieren können — diese Inline-Werte zu einem geteilten Enum hochstufen (siehe Modelle & Enums).
Ein Parameter kann auch mit einer Modelleigenschaft verbunden werden (Spalte Modell-Link), deren Typ er erbt, oder als verworfen markiert werden. Jeder Parameter — sein Typ, sein Enum, seine Verwerfung — findet sich in der generierten Dokumentation und in jeder Protokoll-Projektion wieder.
CRUD generieren
Section titled “CRUD generieren”Aus den Einstellungen eines Modells erstellt CRUD generieren mit einem Klick eine Routengruppe, die nach dem Plural des Modells benannt ist, mit sechs Routen:
| Route | Methode & Pfad | Antworten |
|---|---|---|
| Auflisten | GET / (paginiert) | 200 |
| Abrufen | GET /{{id}} | 200 · 404 |
| Erstellen | POST / | 201 |
| Ersetzen | PUT /{{id}} | 200 · 404 |
| Aktualisieren | PATCH /{{id}} | 200 · 404 |
| Löschen | DELETE /{{id}} | 204 · 404 |
Die Liste ist paginiert (Offset, standardmäßig 20 Elemente, maximal 100).
Jedes {{id}} wird automatisch mit dem Bezeichner des Modells verbunden.
Der Dialog CRUD generieren bietet zwei Optionen:
- Bestehende Routen ersetzen — um Duplikate zu vermeiden, wenn Sie neu generieren.
- Schreibrouten durch Authentifizierung schützen — das Erstellen, das Ersetzen, das Aktualisieren und das Löschen erfordern dann ein Token (Bearer), während die Lesevorgänge öffentlich bleiben.
Er weist auch darauf hin, dass das CRUD in jedem Protokoll bereitgestellt wird: REST-Routen, GraphQL-Abfragen und -Mutationen, gRPC-Methoden, OData-Entitätenmenge und SOAP-Operationen (siehe Das Design als Mock bereitstellen).
Suchrouten generieren
Section titled “Suchrouten generieren”Für jede als searchable markierte Eigenschaft fügt Suchrouten generieren einen Abfrageparameter hinzu, der mit der Auflistungsroute des Modells verbunden ist (und erstellt diese Route, falls sie noch nicht existiert).
Authentifizierung
Section titled “Authentifizierung”Die Authentifizierung wird auf drei Ebenen eingestellt: ein Standardwert des Designs, eine erforderliche Authentifizierung pro Gruppe und ein Überschreiben pro Route (das den Standardwert der Gruppe erbt). Die verfügbaren Modi sind Keine, Bearer (JWT), API-Schlüssel (Header) und Basic.
Die Tags
Section titled “Die Tags”Die Tags gruppieren die Routen für die Dokumentation und den OpenAPI-Export. Sie existieren auf zwei Ebenen: Eine Route trägt ihre eigenen Tags (ihre Registerkarte Definition), und eine Gruppe trägt gemeinsame Tags (ihre Einstellungen), die auf jede ihrer Routen angewendet werden. Die effektiven Tags einer Route sind die Vereinigung beider — ein Tag, das einer ganzen Gruppe gemeinsam ist, wird daher am besten nur einmal auf der Gruppe gesetzt. Wenn Sie eine importierte API in ein Design umwandeln, wird ein Tag, das auf allen Routen einer Gruppe vorhanden ist, automatisch auf die Gruppe angehoben.
Die Verwerfung
Section titled “Die Verwerfung”Eine Route (wie eine Eigenschaft oder ein Parameter) kann über ihre
Einstellungen als verworfen markiert werden. Eine verworfene Route
erscheint ausgegraut in der Routenliste und in den generierten Clients und
trägt einen Verwerfungshinweis auf ihrer Registerkarte. Das Flag propagiert sich
in jede Protokoll-Projektion — das deprecated von OpenAPI, die Direktive
@deprecated von GraphQL, die SOAP- und gRPC-Deskriptoren und die
OData-Metadaten —, damit die Konsumenten jedes bereitgestellten Protokolls es
sehen.