Ruter & CRUD

Ruterne er dit API’s indgangspunkter. De er grupperet efter ressource, og du kan skrive dem i hånden eller generere dem ud fra en model.

Definer en rute

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

Parametre

En rutes fane Definition oplister dens parametre — stiparametre (oprettet ud fra pladsholderne {{param}}) og de forespørgsels- / header-parametre, du tilføjer med Tilføj en parameter. Hver bærer et navn, en placering (i), om den er påkrævet, en beskrivelse og, valgfrit, et eksempel.

Cellen Type er en kombinationsboks: vælg en primitiv (string, integer, number, boolean) eller en af designets navngivne enums med et enkelt klik. For de rigere tilfælde skal du vælge Advanced… for at åbne en lille dialogboks, hvor du kan:

• gøre parameteren til et array og vælge dens elementtype (array<string>, …) — en flerværdi-forespørgselsparameter;
• give den inline-enum-værdier (det tilladte sæt, oplistet som chips), når den ikke er typet af en navngiven enum;
• Udtræk til en navngiven enum — forfrem disse inline-værdier til en delt enum (se Modeller & enums).

En parameter kan også være knyttet til en modelegenskab (kolonnen Modellink) og arver da dens type, eller markeres som udfaset. Hver parameter — dens type, dens enum, dens udfasning — indgår i den genererede dokumentation og i hver protokolprojektion.

Generer CRUD

Fra en models indstillinger opretter Generer CRUD med et klik en gruppe ruter, navngivet efter modellens flertal, med seks ruter:

Rute	Metode & sti	Svar
List	GET / (pagineret)	200
Hent	GET /{{id}}	200 · 404
Opret	POST /	201
Erstat	PUT /{{id}}	200 · 404
Opdater	PATCH /{{id}}	200 · 404
Slet	DELETE /{{id}}	204 · 404

Listen er pagineret (offset, 20 elementer som standard, 100 som maksimum). Hver {{id}} knyttes automatisk til modellens identifikator.

Dialogboksen Generer CRUD tilbyder to muligheder:

• Erstat eksisterende ruter — for at undgå dubletter, hvis du regenererer.
• Beskyt skriveruterne med autentificering — oprettelsen, erstatningen, opdateringen og sletningen kræver da et token (bearer), mens læsningerne forbliver offentlige.

Den minder også om, at CRUD’en serveres i hver protokol: REST-ruter, GraphQL-forespørgsler og -mutationer, gRPC-metoder, OData-entitetssæt og SOAP-operationer (se Server designet som mock).

Generer søgeruterne

For hver egenskab markeret searchable tilføjer Generer søgeruterne en forespørgselsparameter knyttet til modellens listerute (og opretter denne rute, hvis den ikke allerede findes).

Autentificering

Autentificeringen indstilles på tre niveauer: en standardværdi for designet, en påkrævet autentificering per gruppe, og en tilsidesættelse per rute (som arver gruppens standardværdi). De tilgængelige tilstande er Ingen, Bearer (JWT), API-nøgle (header) og Basic.

Tags

Tags grupperer ruter til dokumentationen og OpenAPI-eksporten. De findes på to niveauer: en rute bærer sine egne tags (dens fane Definition), og en gruppe bærer delte tags (dens indstillinger), der anvendes på hver af dens ruter. En rutes effektive tags er foreningen af de to — en tag, der er fælles for en hel gruppe, sættes derfor helst kun én gang på gruppen. Når du omdanner et importeret API til et design, løftes en tag, der findes på alle en gruppes ruter, automatisk op på gruppen.

Udfasning

En rute (ligesom en egenskab eller en parameter) kan markeres som udfaset fra sine Indstillinger. En udfaset rute vises nedtonet i listen over Ruter og i de genererede klienter og bærer en udfasningsnotits på sin fane. Flaget breder sig ud i hver protokolprojektion — OpenAPI’s deprecated, GraphQL’s @deprecated-direktiv, SOAP- og gRPC-deskriptorerne og OData-metadataene — så forbrugerne af hvilken som helst serveret protokol kan se det.