Rutter & CRUD

Rutterna är ditt API:s ingångspunkter. De är grupperade per resurs, och du kan skriva dem för hand eller generera dem utifrån en modell.

Definiera en rutt

En rutt bär en metod, en sökväg, parametrar och svar. Sökvägen använder Restorms syntax {{param}}: så snart du skriver {{id}} i sökvägen visas motsvarande parameter; att ta bort den raderar den.

Parametrar

Fliken Definition för en rutt listar dess parametrar — sökvägsparametrar (skapade utifrån platshållarna {{param}}) och de fråge- / header-parametrar du lägger till med Lägg till en parameter. Var och en bär ett namn, en plats (i), om den är obligatorisk, en beskrivning och, valfritt, ett exempel.

Cellen Typ är en kombinationsruta: välj en primitiv (string, integer, number, boolean) eller en av designens namngivna enumar med ett enda klick. För de rikare fallen, välj Advanced… för att öppna en liten dialogruta där du kan:

• göra parametern till en array och välja dess elementtyp (array<string>, …) — en flervärdes frågeparameter;
• ge den inline-enumvärden (den tillåtna uppsättningen, listad som chips) när den inte typas av en namngiven enum;
• Extrahera till en namngiven enum — befordra dessa inline-värden till en delad enum (se Modeller & enumar).

En parameter kan också vara kopplad till en modellegenskap (kolumnen Modellänk), och ärver då dess typ, eller markeras som föråldrad. Varje parameter — dess typ, dess enum, dess föråldring — återfinns i den genererade dokumentationen och i varje protokollprojektion.

Generera CRUD

Från en modells inställningar skapar Generera CRUD med ett klick en grupp rutter som namnges efter modellens plural, med sex rutter:

Rutt	Metod & sökväg	Svar
Lista	GET / (paginerad)	200
Hämta	GET /{{id}}	200 · 404
Skapa	POST /	201
Ersätta	PUT /{{id}}	200 · 404
Uppdatera	PATCH /{{id}}	200 · 404
Ta bort	DELETE /{{id}}	204 · 404

Listan är paginerad (offset, 20 element som standard, 100 som maximum). Varje {{id}} knyts automatiskt till modellens identifierare.

Dialogrutan Generera CRUD erbjuder två alternativ:

• Ersätt befintliga rutter — för att undvika dubbletter om du regenererar.
• Skydda skrivrutterna med autentisering — skapandet, ersättningen, uppdateringen och borttagningen kräver då en token (bearer), medan läsningarna förblir offentliga.

Den påminner också om att CRUD:en betjänas i varje protokoll: REST-rutter, GraphQL-förfrågningar och -mutationer, gRPC-metoder, OData-entitetsuppsättning och SOAP-operationer (se Betjäna designen som mock).

Generera sökrutterna

För varje egenskap som är markerad searchable lägger Generera sökrutterna till en frågeparameter knuten till modellens listrutt (och skapar denna rutt om den ännu inte finns).

Autentisering

Autentiseringen ställs in på tre nivåer: ett standardvärde för designen, en obligatorisk autentisering per grupp, och en åsidosättning per rutt (som ärver gruppens standardvärde). De tillgängliga lägena är Ingen, Bearer (JWT), API-nyckel (header) och Basic.

Taggar

Taggarna grupperar rutter för dokumentationen och OpenAPI-exporten. De finns på två nivåer: en rutt bär sina egna taggar (dess flik Definition), och en grupp bär delade taggar (dess inställningar) som tillämpas på var och en av dess rutter. En rutts effektiva taggar är unionen av de två — en tagg som är gemensam för en hel grupp sätts därför helst en enda gång på gruppen. När du omvandlar ett importerat API till en design lyfts en tagg som finns på alla rutter i en grupp automatiskt upp på gruppen.

Föråldring

En rutt (liksom en egenskap eller en parameter) kan markeras som föråldrad från sina Inställningar. En föråldrad rutt visas nedtonad i listan över Rutter och i de genererade klienterna, och bär en föråldringsnotis på sin flik. Flaggan sprider sig i varje protokollprojektion — OpenAPI:s deprecated, GraphQL:s direktiv @deprecated, SOAP- och gRPC-deskriptorerna, och OData-metadatan — så att konsumenterna av vilket serverat protokoll som helst ser den.