Reitit & CRUD

Reitit ovat API:si sisääntulopisteet. Ne on ryhmitelty resurssin mukaan, ja voit kirjoittaa ne käsin tai generoida ne mallista.

Reitin määrittely

Reitti kantaa metodin, polun, parametrit ja vastaukset. Polku käyttää Restormin {{param}}-syntaksia: heti kun kirjoitat {{id}} polkuun, vastaava parametri ilmestyy; sen poistaminen poistaa parametrin.

Parametrit

Reitin Määrittely-välilehti luettelee sen parametrit — polkuparametrit (luotu {{param}}-paikkamerkeistä) ja kysely- / otsakeparametrit, jotka lisäät Lisää parametri -toiminnolla. Kukin kantaa nimen, sijainnin (missä), tiedon siitä onko se pakollinen, kuvauksen ja valinnaisesti esimerkin.

Tyyppi-solu on yhdistelmävalikko: valitse primitiivi (string, integer, number, boolean) tai jokin suunnitelman nimetyistä enumeista yhdellä napsautuksella. Rikkaampia tapauksia varten valitse Advanced… avataksesi pienen ikkunan, jossa voit:

• tehdä parametrista taulukon ja valita sen elementtityypin (array<string>, …) — monivalintainen kyselyparametri;
• antaa sille inline-enum-arvoja (sallittu joukko, lueteltuna merkkeinä), kun sitä ei tyypitä nimetty enum;
• Erota nimetyksi enumiksi — ylentää nämä inline-arvot jaetuksi enumiksi (katso Mallit ja enumit).

Parametri voidaan myös kytkeä mallin ominaisuuteen (Mallilinkki-sarake), jolta se perii tyypin, tai merkitä vanhentuneeksi. Jokainen parametri — sen tyyppi, sen enum, sen vanhentuminen — virtaa generoituun dokumentaatioon ja jokaiseen protokollaprojektioon.

Generoi CRUD

Mallin asetuksista Generoi CRUD luo yhdellä napsautuksella reittiryhmän, joka on nimetty mallin monikon mukaan, kuudella reitillä:

Reitti	Metodi & polku	Vastaukset
Listaa	GET / (sivutettu)	200
Hae	GET /{{id}}	200 · 404
Luo	POST /	201
Korvaa	PUT /{{id}}	200 · 404
Päivitä	PATCH /{{id}}	200 · 404
Poista	DELETE /{{id}}	204 · 404

Lista on sivutettu (offset, oletuksena 20 elementtiä, enintään 100). Jokainen {{id}} on automaattisesti kytketty mallin tunnisteeseen.

Generoi CRUD -valintaikkuna tarjoaa kaksi vaihtoehtoa:

• Korvaa olemassa olevat reitit — kaksoiskappaleiden välttämiseksi, jos generoit uudelleen.
• Suojaa kirjoitusreitit todennuksella — luonti, korvaus, päivitys ja poisto vaativat tällöin tokenin (bearer), kun taas luvut pysyvät julkisina.

Se muistuttaa myös, että CRUD tarjoillaan jokaisessa protokollassa: REST-reitit, GraphQL-kyselyt ja -mutaatiot, gRPC-metodit, OData-entiteettijoukko ja SOAP-operaatiot (katso Suunnitelman tarjoilu mockina).

Generoi hakureitit

Jokaiselle searchable-merkityllä ominaisuudelle Generoi hakureitit lisää kyselyparametrin, joka on kytketty mallin listareittiin (ja luo tämän reitin, jos sitä ei vielä ole).

Todennus

Todennus säädetään kolmella tasolla: suunnitelman oletusarvo, ryhmäkohtainen vaadittu todennus, ja reittikohtainen ohitus (joka perii ryhmän oletusarvon). Käytettävissä olevat tilat ovat Ei mitään, Bearer (JWT), API-avain (otsake) ja Basic.

Tunnisteet

Tunnisteet ryhmittelevät reitit dokumentaatiota ja OpenAPI-vientiä varten. Ne elävät kahdella tasolla: reitillä on omat tunnisteensa (sen Määrittely-välilehti), ja ryhmällä on jaetut tunnisteet (sen asetukset), joita sovelletaan jokaiseen sen sisältämään reittiin. Reitin tehokkaat tunnisteet ovat näiden kahden yhdiste — koko ryhmälle yhteinen tunniste kannattaa siksi asettaa kerran ryhmään. Kun muunnat tuodun API:n suunnitelmaksi, ryhmän kaikilla reiteillä esiintyvä tunniste nostetaan automaattisesti ryhmään.

Vanhentuminen

Reitti (kuten ominaisuus tai parametri) voidaan merkitä vanhentuneeksi sen Asetuksista. Vanhentunut reitti näkyy himmennettynä Reitit-listassa ja generoiduissa asiakkaissa, ja kantaa vanhentumisvaroituksen välilehdellään. Lippu kulkee jokaiseen protokollaprojektioon — OpenAPI:n deprecated, GraphQL:n @deprecated-direktiivi, SOAP- ja gRPC-kuvaajat sekä OData-metatiedot — jotta minkä tahansa tarjoillun protokollan kuluttajat näkevät sen.