Routes & CRUD

De routes zijn de toegangspunten van uw API. Ze zijn gegroepeerd per resource, en u kunt ze met de hand schrijven of genereren vanuit een model.

Een route definiëren

Een route draagt een methode, een pad, parameters en antwoorden. Het pad gebruikt de syntaxis {{param}} van Restorm: zodra u {{id}} in het pad typt, verschijnt de bijbehorende parameter; die verwijderen wist hem.

De parameters

Het tabblad Definitie van een route somt zijn parameters op — de padparameters (aangemaakt uit de plaatshouders {{param}}) en de query-/headerparameters die u toevoegt met Een parameter toevoegen. Elke draagt een naam, een locatie (in), zijn vereist-karakter, een beschrijving en, optioneel, een voorbeeld.

De cel Type is een combo: kies met één klik een primitief (string, integer, number, boolean) of een van de benoemde enums van het ontwerp. Voor de rijkere gevallen kiest u Advanced… om een klein venster te openen waar u:

• van de parameter een array kunt maken en zijn elementtype kunt kiezen (array<string>, …) — een query-parameter met meerdere waarden;
• die inline enum-waarden kunt geven (de toegestane verzameling, opgesomd als chips) wanneer die niet getypeerd is door een benoemde enum;
• Naar een benoemde enum extraheren kunt — die inline waarden promoveren tot een gedeelde enum (zie Modellen & enums).

Een parameter kan ook gekoppeld zijn aan een modeleigenschap (kolom Modelkoppeling), waarvan hij het type erft, of gemarkeerd worden als verouderd. Elke parameter — zijn type, zijn enum, zijn veroudering — komt terug in de gegenereerde documentatie en in elke protocolprojectie.

CRUD genereren

Vanuit de instellingen van een model maakt CRUD genereren met één klik een groep routes, genoemd naar het meervoud van het model, met zes routes:

Route	Methode & pad	Antwoorden
Opsommen	GET / (gepagineerd)	200
Ophalen	GET /{{id}}	200 · 404
Aanmaken	POST /	201
Vervangen	PUT /{{id}}	200 · 404
Bijwerken	PATCH /{{id}}	200 · 404
Verwijderen	DELETE /{{id}}	204 · 404

De lijst is gepagineerd (offset, standaard 20 elementen, maximaal 100). Elke {{id}} wordt automatisch verbonden met de identificator van het model.

Het dialoogvenster CRUD genereren biedt twee opties:

• Bestaande routes vervangen — om duplicaten te vermijden als u opnieuw genereert.
• De schrijfroutes beschermen met authenticatie — het aanmaken, het vervangen, het bijwerken en het verwijderen vereisen dan een token (bearer), terwijl de leesacties openbaar blijven.

Het herinnert er ook aan dat de CRUD in elk protocol wordt bediend: REST-routes, GraphQL-queries en -mutaties, gRPC-methoden, OData-entiteitenset en SOAP-bewerkingen (zie Het ontwerp als mock bedienen).

De zoekroutes genereren

Voor elke als searchable gemarkeerde eigenschap voegt De zoekroutes genereren een queryparameter toe die verbonden is met de opsomroute van het model (en maakt die route aan als die nog niet bestaat).

Authenticatie

De authenticatie wordt op drie niveaus ingesteld: een standaardwaarde van het ontwerp, een vereiste authenticatie per groep, en een overschrijving per route (die de standaardwaarde van de groep erft). De beschikbare modi zijn Geen, Bearer (JWT), API-sleutel (header) en Basic.

De tags

De tags groeperen de routes voor de documentatie en de OpenAPI-export. Ze bestaan op twee niveaus: een route draagt haar eigen tags (haar tabblad Definitie), en een groep draagt gedeelde tags (haar instellingen) die op elk van haar routes worden toegepast. De effectieve tags van een route zijn de unie van beide — een tag die een hele groep gemeen heeft, wordt daarom bij voorkeur één keer op de groep gezet. Wanneer u een geïmporteerde API in een ontwerp omzet, wordt een tag die op alle routes van een groep aanwezig is, automatisch naar de groep opgetild.

De veroudering

Een route (zoals een eigenschap of een parameter) kan als verouderd gemarkeerd worden vanuit haar Instellingen. Een verouderde route wordt grijs weergegeven in de lijst met Routes en in de gegenereerde clients, en draagt een verouderingswaarschuwing op haar tabblad. De vlag propageert naar elke protocolprojectie — het deprecated van OpenAPI, de @deprecated-directive van GraphQL, de SOAP- en gRPC-descriptors, en de OData-metadata — zodat consumenten van elk bediend protocol het zien.