Rrugët & CRUD

Rrugët janë pikat e hyrjes së API-t tuaj. Ato grupohen sipas burimit, dhe ju mund t’i shkruani me dorë ose t’i gjeneroni nga një model.

Përcaktimi i një rruge

Një rrugë mbart një metodë, një shteg, parametra dhe përgjigje. Shtegu përdor sintaksën {{param}} të Restorm: sapo shtypni {{id}} në shteg, parametri përkatës shfaqet; heqja e tij e fshin atë.

Parametrat

Skeda Përcaktimi e një rruge liston parametrat e saj — parametrat e shtegut (të krijuar nga vendmbajtësit {{param}}) dhe parametrat e kërkesës / header-it që shtoni me Shto një parametër. Secili mban një emër, një vendndodhje (in), karakterin e tij të kërkuar, një përshkrim dhe, opsionalisht, një shembull.

Qeliza Tipi është një combo: zgjidhni një primitiv (string, integer, number, boolean) ose një nga enum-et e emërtuara të dizajnit me një klik të vetëm. Për rastet më të pasura, zgjidhni Advanced… për të hapur një dritare të vogël ku mund të:

• e bëni parametrin një varg dhe të zgjidhni tipin e elementit të tij (array<string>, …) — një parametër kërkese me shumë vlera;
• t’i jepni vlera enum-i inline (grupi i lejuar, i listuar si distinktivë) kur nuk është i tipizuar nga një enum i emërtuar;
• Nxirr në një enum të emërtuar — të promovoni këto vlera inline në një enum të përbashkët (shihni Modelet & enum-et).

Një parametër mund gjithashtu të lidhet me një veti modeli (kolona Lidhje modeli), prej së cilës trashëgon tipin, ose të shënohet i hequr nga përdorimi. Çdo parametër — tipi i tij, enum-i i tij, heqja e tij nga përdorimi — gjendet në dokumentacionin e gjeneruar dhe në çdo projeksion protokolli.

Gjenero CRUD

Nga cilësimet e një modeli, Gjenero CRUD krijon me një klik një grup rrugësh të emërtuar sipas shumësit të modelit, me gjashtë rrugë:

Rruga	Metoda & shtegu	Përgjigjet
Listo	GET / (i faqosur)	200
Merr	GET /{{id}}	200 · 404
Krijo	POST /	201
Zëvendëso	PUT /{{id}}	200 · 404
Përditëso	PATCH /{{id}}	200 · 404
Fshij	DELETE /{{id}}	204 · 404

Lista është e faqosur (offset, 20 elemente si parazgjedhje, 100 maksimumi). Çdo {{id}} lidhet automatikisht me identifikuesin e modelit.

Dialogu Gjenero CRUD ofron dy opsione:

• Zëvendëso rrugët ekzistuese — për të shmangur dublikatat nëse rigjeneroni.
• Mbroj rrugët e shkrimit me autentikim — krijimi, zëvendësimi, përditësimi dhe fshirja kërkojnë atëherë një token (bearer), ndërsa leximet mbeten publike.

Ai kujton gjithashtu se CRUD-i shërbehet në çdo protokoll: rrugë REST, kërkesa dhe mutacione GraphQL, metoda gRPC, grup entitetesh OData dhe operacione SOAP (shihni Shërbimi i dizajnit si mock).

Gjenero rrugët e kërkimit

Për çdo veti të shënuar searchable, Gjenero rrugët e kërkimit shton një parametër kërkese të lidhur me rrugën e listimit të modelit (dhe krijon këtë rrugë nëse ende nuk ekziston).

Autentikimi

Autentikimi rregullohet në tre nivele: një vlerë e paracaktuar e dizajnit, një autentikim i kërkuar për grup, dhe një mbivendosje për rrugë (që trashëgon parazgjedhjen e grupit). Mënyrat e disponueshme janë Asnjë, Bearer (JWT), Çelës API (header) dhe Basic.

Etiketat

Etiketat grupojnë rrugët për dokumentacionin dhe eksportin OpenAPI. Ato jetojnë në dy nivele: një rrugë mban etiketat e saj të veta (skeda e saj Përcaktimi), dhe një grup mban etiketa të përbashkëta (cilësimet e tij) të zbatuara për secilën nga rrugët e tij. Etiketat efektive të një rruge janë bashkimi i të dyjave — kështu që një etiketë e përbashkët për një grup të tërë vendoset mundësisht një herë të vetme mbi grupin. Kur shndërroni një API të importuar në dizajn, një etiketë e pranishme në të gjitha rrugët e një grupi ngrihet automatikisht mbi grupin.

Heqja nga përdorimi

Një rrugë (si një veti apo një parametër) mund të shënohet e hequr nga përdorimi nga Cilësimet e saj. Një rrugë e hequr nga përdorimi shfaqet e zbehur në listën e Rrugëve dhe në klientët e gjeneruar, dhe mban një paralajmërim heqjeje nga përdorimi mbi skedën e saj. Flamuri përhapet në çdo projeksion protokolli — deprecated i OpenAPI, direktiva @deprecated e GraphQL, përshkruesit SOAP dhe gRPC, dhe metadata OData — që konsumatorët e çdo protokolli të shërbyer ta shohin.