ApiDecider a endpointy
Tomaj\NetteApi\ApiDecider je zoznam endpointov. ApiPresenter sa ho raz za požiadavku spýta, ktorý handler, autorizáciu a obmedzenie požiadaviek použiť.
Registrácia endpointov
public function addApi(
EndpointInterface $endpointIdentifier,
ApiHandlerInterface|string $handler,
ApiAuthorizationInterface $apiAuthorization,
RateLimiterInterface|RateLimitInterface|null $rateLimit = new AutowiredRateLimit()
): selfV NEON:
services:
apiDecider:
factory: Tomaj\NetteApi\ApiDecider
setup:
- addApi(Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'users'), App\Api\UserListHandler, Tomaj\NetteApi\Authorization\NoAuthorization())
- addApi(Tomaj\NetteApi\EndpointIdentifier('POST', 1, 'users'), '@userCreateHandler', @bearer, @writeLimit)
- addApi(Tomaj\NetteApi\EndpointIdentifier('GET', 2, 'users', 'detail'), App\Api\UserDetailV2Handler(), @bearer)Štvrtý argument je obmedzenie požiadaviek, null znamená žiadne. Keď chýba, použije sa autowirovaná služba RateLimitInterface z 3.x, pri viacerých addApi() vyhodí LogicException, ktorá ich vymenuje; RateLimiterInterface sa neautowiruje. Pozrite si Obmedzenie požiadaviek.
EndpointIdentifier
| Argument | Príklad | Poznámka |
|---|---|---|
| metóda | 'GET' | porovnáva sa veľkými písmenami |
| verzia | 1, '1.1' | uloží sa ako reťazec, nesmie obsahovať / |
| balík | 'users' | prvý segment cesty za verziou |
| apiAction | 'detail', '{id}/detail' alebo null | voliteľný druhý segment; {name} z neho robí šablónu URL, pozrite nižšie |
getUrl() vráti v1/users/detail, čo používa OpenAPI aj konzola.
Ako sa hľadá zhoda
getApi($method, $version, $package, $apiAction):
- zmení metódu na veľké písmená a prázdnu
apiActionnanull; - prechádza endpointy v poradí, v akom boli pridané;
- vráti prvý, kde sa zhoduje metóda, verzia, balík aj akcia;
- nastaví handleru endpoint, takže fungujú
getEndpoint()acreateLink(); - bez zhody vráti
DefaultHandleraNoAuthorization, ktoré odpovedia404 Unknown api endpointcez metóduhandleNotFound()error handlera.
getApi() si ponecháva svoje štyri argumenty, takže podtrieda, ktorá ho prekrýva, ďalej funguje, a nájde len endpointy so statickou URL.
Endpointy so segmentmi
Endpoint, ktorého akcia má segmenty {name}, napríklad users/{id}/detail, nájde matchPath($method, $version, $package, $apiAction, $params) z hodnôt, ktoré rozparsoval router; $params sú segmenty za akciou (<params> z routy). ApiPresenter najprv zavolá getApi() a keď ten nič nenájde, zavolá matchPath(), takže pri tej istej URL vyhrá statický endpoint. Keď má URL za akciou ďalšie segmenty, ApiPresenter skúsi matchPath() ako prvé: šablóna, ktorá zodpovedá celej ceste, napríklad users/{id}/detail pre /users/7/detail, vyhrá nad kratším statickým endpointom users/7. matchPath() porovná cestu so všetkými šablónami danej metódy a verzie, uloží zhodné hodnoty pre parametre z cesty a vráti Api, alebo null, keď nezodpovedá žiadna šablóna. getApi() nájde šablónu iba podľa jej doslovnej URL, napríklad getApi('GET', '1', 'users', '{id}/detail'), takto ju otvára API konzola. addApi() vyhodí LogicException pri chybnom segmente {name} a pri dvoch šablónach, ktoré môžu zodpovedať jednej ceste, a vymenuje ich; s DI rozšírením takéto šablóny zastavia už kompiláciu kontajnera. Zmeňte statický segment tak, aby sa líšili. Globálny preflight odpovie na OPTIONS aj pre cestu, ktorá zodpovedá šablóne. Ako šablónu zaregistrovať a smerovať, je na stránke Typovaný vstup.
GET /api/v1/users a POST /api/v1/users sú dva endpointy s dvoma handlermi. Nezaregistrovaná verzia, napríklad /api/v3/users, je 404, ako testuje príklad verzií.
Tri spôsoby, ako odovzdať handler
| Hodnota | Vytvorí sa |
|---|---|
App\Api\UserListHandler (názov triedy) | až pri volaní endpointu, getByType() z kontajnera |
'@userCreateHandler' (názov služby) | až pri volaní, getByName() |
App\Api\UserDetailV2Handler() (objekt) | pri vytvorení decidera |
Názov triedy alebo služby udrží začiatok každej požiadavky rýchly, pretože sa vytvorí iba volaný handler a jeho závislosti. Viac v Handleroch.
Na úvodzovkách záleží. '@userCreateHandler' v úvodzovkách je obyčajný reťazec, názov služby, ktorý ApiDecider vyhľadá až pri volaní endpointu. Bez úvodzoviek, ako pri @bearer a @writeLimit vyššie, Nette vloží priamo službu, takže sa vytvorí spolu s deciderom. Pre malé objekty autorizácie a obmedzenia požiadaviek to nevadí; pre handlery s ťažkými závislosťami použite názov v úvodzovkách alebo názov triedy.
Preflight pre všetky endpointy
enableGlobalPreflight() odpovie na OPTIONS pre každú zaregistrovanú URL cez CorsPreflightHandler, bez addApi() pre každý endpoint. Pozrite si CORS.
Zoznam endpointov
getApis() vráti každý endpoint s handlerom, autorizáciou a obmedzením požiadaviek. Stavia na ňom OpenApiHandler aj ApiListingControl. Pozor, vytvorí pri tom každý handler.
Časté otázky
Čo sa stane s dvoma rovnakými endpointmi?
Vyhrá prvý pridaný; druhý sa nikdy nezavolá.
Porovnáva sa verzia ako číslo?
Nie, ako reťazec. 1 a '1' sa zhodujú, '1.0' sa s 1 nezhoduje.
Môže balík obsahovať lomku?
Nie, routa berie jeden segment. Pre druhú úroveň použite apiAction.
Môžem použiť inú štruktúru URL?
Áno, zmeňte routu, pokiaľ naplní version, package a voliteľne apiAction.
Prečo sa môj handler vytvára pri každej požiadavke?
Bol odovzdaný ako objekt, App\Api\Handler(), alebo sa volalo getApis(). Odovzdajte radšej názov triedy.