Ruter & CRUD

Rutene er inngangspunktene til API-et ditt. De er gruppert etter ressurs, og du kan skrive dem for hånd eller generere dem ut fra en modell.

Definer en rute

En rute bærer en metode, en sti, parametere og svar. Stien bruker Restorms syntaks {{param}}: så snart du skriver {{id}} i stien, vises den tilsvarende parameteren; å fjerne den sletter den.

Parametere

Fanen Definisjon til en rute lister opp parameterne dens — stiparametere (opprettet ut fra plassholderne {{param}}) og de spørrings- / header-parameterne du legger til med Legg til en parameter. Hver av dem bærer et navn, en plassering (i), om den er påkrevd, en beskrivelse og, valgfritt, et eksempel.

Cellen Type er en kombinasjonsboks: velg en primitiv (string, integer, number, boolean) eller en av designets navngitte enums med ett enkelt klikk. For de rikere tilfellene velger du Advanced… for å åpne en liten dialogboks der du kan:

• gjøre parameteren til et array og velge elementtypen dens (array<string>, …) — en spørringsparameter med flere verdier;
• gi den inline-enum-verdier (det tillatte settet, listet opp som chips) når den ikke er typet av en navngitt enum;
• Trekk ut til en navngitt enum — forfrem disse inline-verdiene til en delt enum (se Modeller & enums).

En parameter kan også være knyttet til en modellegenskap (kolonnen Modellenke) og arver da typen dens, eller markeres som avviklet. Hver parameter — typen dens, enumen dens, avviklingen dens — inngår i den genererte dokumentasjonen og i hver protokollprojeksjon.

Generer CRUD

Fra innstillingene til en modell oppretter Generer CRUD med ett klikk en gruppe ruter, navngitt etter flertallsformen av modellen, med seks ruter:

Rute	Metode & sti	Svar
List	GET / (paginert)	200
Hent	GET /{{id}}	200 · 404
Opprett	POST /	201
Erstatt	PUT /{{id}}	200 · 404
Oppdater	PATCH /{{id}}	200 · 404
Slett	DELETE /{{id}}	204 · 404

Listen er paginert (offset, 20 elementer som standard, 100 som maksimum). Hver {{id}} knyttes automatisk til identifikatoren til modellen.

Dialogboksen Generer CRUD tilbyr to alternativer:

• Erstatt eksisterende ruter — for å unngå duplikater hvis du regenererer.
• Beskytt skriverutene med autentisering — opprettelsen, erstatningen, oppdateringen og slettingen krever da et token (bearer), mens lesingene forblir offentlige.

Den minner også om at CRUD-en serveres i hver protokoll: REST-ruter, GraphQL-forespørsler og -mutasjoner, gRPC-metoder, OData-entitetssett og SOAP-operasjoner (se Server designet som mock).

Generer søkerutene

For hver egenskap merket searchable legger Generer søkerutene til en spørringsparameter knyttet til listeruten til modellen (og oppretter denne ruten hvis den ikke allerede finnes).

Autentisering

Autentiseringen stilles inn på tre nivåer: en standardverdi for designet, en påkrevd autentisering per gruppe, og en overstyring per rute (som arver standardverdien til gruppen). De tilgjengelige modusene er Ingen, Bearer (JWT), API-nøkkel (header) og Basic.

Tags

Tags grupperer ruter for dokumentasjonen og OpenAPI-eksporten. De finnes på to nivåer: en rute bærer sine egne tags (fanen Definisjon dens), og en gruppe bærer delte tags (innstillingene dens) som anvendes på hver av rutene den inneholder. De effektive taggene til en rute er unionen av de to — en tag som er felles for en hel gruppe, settes derfor helst bare én gang på gruppen. Når du gjør om et importert API til et design, løftes en tag som finnes på alle rutene i en gruppe, automatisk opp på gruppen.

Avvikling

En rute (som en egenskap eller en parameter) kan markeres som avviklet fra Innstillingene sine. En avviklet rute vises nedtonet i listen over Ruter og i de genererte klientene, og bærer et avviklingsvarsel på fanen sin. Flagget sprer seg i hver protokollprojeksjon — OpenAPI-ens deprecated, GraphQL-ens @deprecated-direktiv, SOAP- og gRPC-deskriptorene og OData-metadataene — slik at forbrukerne av et hvilket som helst servert protokoll ser det.