Útvonalak & CRUD

Az útvonalak az API-ja belépési pontjai. Erőforrás szerint vannak csoportosítva, és megírhatja őket kézzel, vagy generálhatja őket egy modellből.

Egy útvonal meghatározása

Egy útvonal egy metódust, egy útvonalat, paramétereket és válaszokat hordoz. Az útvonal a Restorm {{param}} szintaxisát használja: amint beírja a {{id}}-t az útvonalba, megjelenik a megfelelő paraméter; ha kiveszi, törlődik.

A paraméterek

Egy útvonal Definíció lapja felsorolja a paramétereit — az útvonal-paramétereket (amelyeket a {{param}} helyőrzőkből hoz létre) és a lekérdezési / fejléc-paramétereket, amelyeket a Paraméter hozzáadása gombbal ad hozzá. Mindegyik hordoz egy nevet, egy elhelyezkedést (hol), a kötelező jellegét, egy leírást és opcionálisan egy példát.

A Típus cella egy kombinált lista: válasszon egy primitívet (string, integer, number, boolean) vagy a terv egyik nevesített enumját egyetlen kattintással. A gazdagabb esetekhez válassza az Advanced… lehetőséget, hogy egy kis ablakot nyisson meg, ahol:

• a paramétert tömbbé teheti, és kiválaszthatja az elemtípusát (array<string>, …) — egy többértékű lekérdezési paraméter;
• beágyazott enum-értékeket adhat neki (az engedélyezett készlet, zsetonként felsorolva), amikor nem egy nevesített enum típusozza;
• Kiemelés nevesített enummá — ezeket a beágyazott értékeket egy megosztott enummá léptetheti elő (lásd Modellek és enumok).

Egy paraméter egy modell tulajdonságához is köthető (a Modellhivatkozás oszlop), amelytől örökli a típust, vagy megjelölhető elavultként. Minden paraméter — a típusa, az enumja, az elavultsága — bekerül a generált dokumentációba és minden protokollvetületbe.

CRUD generálása

Egy modell beállításaiból a CRUD generálása egyetlen kattintással létrehoz egy útvonalcsoportot, amelyet a modell többes száma alapján neveznek el, hat útvonallal:

Útvonal	Metódus & útvonal	Válaszok
Listázás	GET / (lapozott)	200
Lekérés	GET /{{id}}	200 · 404
Létrehozás	POST /	201
Csere	PUT /{{id}}	200 · 404
Frissítés	PATCH /{{id}}	200 · 404
Törlés	DELETE /{{id}}	204 · 404

A lista lapozott (offset, alapértelmezetten 20 elem, legfeljebb 100). Minden {{id}} automatikusan a modell azonosítójához van kötve.

A CRUD generálása párbeszédablak két lehetőséget kínál:

• Meglévő útvonalak cseréje — a duplikátumok elkerülésére, ha újragenerál.
• Az írási útvonalak védelme hitelesítéssel — a létrehozás, csere, frissítés és törlés ekkor tokent (bearer) igényel, míg az olvasások nyilvánosak maradnak.

Emlékeztet arra is, hogy a CRUD minden protokollon kiszolgálódik: REST útvonalak, GraphQL lekérdezések és mutációk, gRPC metódusok, OData entitáskészlet és SOAP műveletek (lásd A terv kiszolgálása mockként).

Keresési útvonalak generálása

Minden searchable-nek jelölt tulajdonsághoz a Keresési útvonalak generálása hozzáad egy lekérdezési paramétert, amely a modell listázási útvonalához van kötve (és létrehozza ezt az útvonalat, ha még nem létezik).

Hitelesítés

A hitelesítés három szinten állítható be: a terv egy alapértelmezett értéke, csoportonként egy kötelező hitelesítés, és útvonalanként egy felülírás (amely a csoport alapértelmezését örökli). Az elérhető módok: Semmi, Bearer (JWT), API-kulcs (fejléc) és Basic.

A címkék

A címkék csoportosítják az útvonalakat a dokumentáció és az OpenAPI-export számára. Két szinten léteznek: egy útvonal a saját címkéit hordozza (a Definíció lapján), egy csoport pedig megosztott címkéket hordoz (a beállításaiban), amelyek minden útvonalára érvényesek. Egy útvonal tényleges címkéi a kettő uniója — így egy egész csoportra közös címkét érdemes egyszer, a csoporton beállítani. Amikor egy importált API-t tervvé alakít, a csoport minden útvonalán jelen lévő címke automatikusan felkerül a csoportra.

Az elavulás

Egy útvonal (akárcsak egy tulajdonság vagy egy paraméter) megjelölhető elavultként a Beállításaiból. Egy elavult útvonal halványítva jelenik meg az Útvonalak listájában és a generált kliensekben, és elavultsági figyelmeztetést hordoz a lapján. A jelző minden protokollvetületbe átterjed — az OpenAPI deprecated mezőjébe, a GraphQL @deprecated direktívájába, a SOAP és gRPC deszkriptorokba és az OData metaadatokba —, hogy bármely kiszolgált protokoll fogyasztói lássák.