Rute i CRUD

Rute su ulazne točke vašeg API-ja. Grupirane su po resursu i možete ih pisati ručno ili ih generirati iz modela.

Definiranje rute

Ruta nosi metodu, putanju, parametre i odgovore. Putanja koristi sintaksu {{param}} iz Restorma: čim upišete {{id}} u putanju, pojavljuje se odgovarajući parametar; njegovim uklanjanjem se briše.

Parametri

Kartica Definiranje rute popisuje njezine parametre — parametre putanje (stvorene iz rezerviranih mjesta {{param}}) i parametre upita / zaglavlja koje dodajete pomoću Dodaj parametar. Svaki nosi naziv, lokaciju (in), svoju obaveznost, opis i, opcionalno, primjer.

Ćelija Tip je combo: odaberite primitiv (string, integer, number, boolean) ili jedan od imenovanih enuma dizajna jednim klikom. Za bogatije slučajeve odaberite Advanced… kako biste otvorili mali prozor u kojem možete:

• pretvoriti parametar u polje i odabrati njegov tip elementa (array<string>, …) — viševrijednosni parametar upita;
• dati mu ugrađene vrijednosti enuma (dopušteni skup, popisan kao bedževi) kada nije tipiziran imenovanim enumom;
• Izdvoji u imenovani enum — promaknuti te ugrađene vrijednosti u dijeljeni enum (vidi Modeli i enumi).

Parametar se također može povezati sa svojstvom modela (stupac Poveznica s modelom), od kojeg nasljeđuje tip, ili se označiti zastarjelim. Svaki parametar — njegov tip, njegov enum, njegova zastarjelost — nalazi se u generiranoj dokumentaciji i u svakoj projekciji protokola.

Generiranje CRUD-a

Iz postavki modela Generiraj CRUD jednim klikom stvara grupu ruta nazvanu prema množini modela, sa šest ruta:

Ruta	Metoda i putanja	Odgovori
Popis	GET / (paginirano)	200
Dohvati	GET /{{id}}	200 · 404
Stvori	POST /	201
Zamijeni	PUT /{{id}}	200 · 404
Ažuriraj	PATCH /{{id}}	200 · 404
Izbriši	DELETE /{{id}}	204 · 404

Popis je paginiran (pomak/offset, 20 elemenata zadano, 100 najviše). Svaki {{id}} automatski je povezan s identifikatorom modela.

Dijaloški okvir Generiraj CRUD nudi dvije opcije:

• Zamijeni postojeće rute — kako biste izbjegli duplikate kada ponovno generirate.
• Zaštiti rute za pisanje autentifikacijom — stvaranje, zamjena, ažuriranje i brisanje tada zahtijevaju token (bearer), dok čitanja ostaju javna.

Također podsjeća da se CRUD poslužuje u svakom protokolu: REST rute, GraphQL upiti i mutacije, gRPC metode, OData skup entiteta i SOAP operacije (vidi Posluživanje dizajna kao mock).

Generiranje ruta pretraživanja

Za svako svojstvo označeno kao searchable, Generiraj rute pretraživanja dodaje parametar upita povezan s rutom popisa modela (i stvara tu rutu ako još ne postoji).

Autentifikacija

Autentifikacija se postavlja na tri razine: zadana vrijednost dizajna, potrebna autentifikacija po grupi i nadjačavanje po ruti (koje nasljeđuje zadanu vrijednost grupe). Dostupni načini su Nijedan, Bearer (JWT), API ključ (zaglavlje) i Basic.

Oznake

Oznake grupiraju rute za dokumentaciju i OpenAPI izvoz. Postoje na dvije razine: ruta nosi vlastite oznake (svoja kartica Definiranje), a grupa nosi dijeljene oznake (svoje postavke) primijenjene na svaku njezinu rutu. Djelotvorne oznake rute su unija dviju — pa se oznaka zajednička cijeloj grupi najbolje postavlja jednom na grupi. Kada uvezeni API pretvorite u dizajn, oznaka prisutna na svim rutama grupe automatski se podiže na grupu.

Zastarjelost

Ruta (poput svojstva ili parametra) može se označiti zastarjelom iz svojih Postavki. Zastarjela ruta prikazuje se zasivljeno u popisu Ruta i u generiranim klijentima te nosi upozorenje o zastarjelosti na svojoj kartici. Zastavica se propagira u svaku projekciju protokola — OpenAPI deprecated, GraphQL direktiva @deprecated, SOAP i gRPC deskriptori te OData metapodaci — kako bi je potrošači bilo kojeg posluženog protokola vidjeli.