Nette APIRobustné REST API priamo vo vašej Nette aplikácii

Ako to vyzerá ​

Handler je jedna trieda:

<?php

declare(strict_types=1);

namespace App\Api;

use Tomaj\NetteApi\Handlers\BaseHandler;
use Tomaj\NetteApi\Params\GetInputParam;
use Tomaj\NetteApi\Response\JsonApiResponse;
use Tomaj\NetteApi\Response\ResponseInterface;

final class HelloHandler extends BaseHandler
{
    public function summary(): string
    {
        return 'Say hello';
    }

    public function params(): array
    {
        return [
            (new GetInputParam('name'))->setDefault('world')->setDescription('Who to greet'),
        ];
    }

    public function handle(array $params): ResponseInterface
    {
        return new JsonApiResponse(200, ['message' => 'Hello ' . $params['name'] . '!']);
    }
}

a niekoľko riadkov konfigurácie ho zaregistruje ako GET /api/v1/hello:

application:
	mapping:
		# Api:Api:default is Tomaj\NetteApi\Presenters\ApiPresenter
		Api: Tomaj\NetteApi\Presenters\*Presenter

services:
	router: App\RouterFactory::create

	# Nette 3.3 creates presenters only from the DI container
	apiPresenter:
		factory: Tomaj\NetteApi\Presenters\ApiPresenter

	# required by ApiPresenter: when to validate output schemas and show error details
	- Tomaj\NetteApi\Output\Configurator\DebuggerConfigurator
	# required by ApiPresenter: turns errors into JSON responses
	- Tomaj\NetteApi\Error\DefaultErrorHandler

	apiDecider:
		factory: Tomaj\NetteApi\ApiDecider
		setup:
			# GET /api/v1/hello
			- addApi(
				Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'hello'),
				App\Api\HelloHandler(),
				Tomaj\NetteApi\Authorization\NoAuthorization()
			)

Príklad hello world spúšťa presne tento kód v CI.

Kam ďalej ​

• ZačínameInštalácia knižnice, routa a prvý endpoint.
• ArchitektúraČo sa deje s požiadavkou, krok za krokom.
• PríkladyTrinásť spustiteľných projektov, testovaných pri každom pushi.
• ReferenciaVšetky triedy a rozhrania verzie 3.x.

Časté otázky ​

Čo je Nette API? ​

Knižnica, ktorá do Nette aplikácie pridá REST API vrstvu: endpointy, validované parametre aj výstupy, autorizáciu, CORS, obmedzenie požiadaviek, logovanie a OpenAPI dokument. Pozrite si Začíname.

Ako zapadá do Nette aplikácie? ​

Cez jednu routu na jej ApiPresenter a služby zaregistrované v neon konfigurácii, takže handlery dostanú závislosti z Nette DI ako každá iná služba. Pozrite si Začíname.

Aké verzie PHP a Nette potrebuje Nette API 3.x? ​

PHP 8.3 alebo novšie, nette/application a nette/http 3.x a Latte 3. Celý zoznam je v časti Začíname.

Musím pre endpointy písať presentery? ​

Nie. Knižnica má vlastný ApiPresenter a váš kód je v handleroch. Pozrite si Handlery.

Ako fungujú verzie API? ​

Verzia je súčasťou každého endpointu, takže v1 a v2 tej istej URL môžu viesť na rôzne handlery. Pozrite si Odkazy a verzie a príklad verzií.

Ako ochránim endpoint? ​

Pri registrácii mu dajte autorizáciu: bearer token, API kľúč v hlavičke, query alebo cookie, alebo vlastnú triedu. Pozrite si Autorizáciu.

Spomalí to každú požiadavku? ​

Handlery zaregistrované názvom triedy sa vytvoria z DI kontajnera až pri volaní ich endpointu. Výnimkou sú endpointy OpenAPI, zoznamu a konzoly: čítajú všetky endpointy cez getApis(), a tým vytvoria všetky handlery. Pozrite si Architektúru.

Dá sa z kódu vygenerovať dokumentácia API? ​

Áno. Zaregistrujte OpenApiHandler a ten opíše každý endpoint ako OpenAPI 3.0, v JSON alebo YAML. Pozrite si OpenAPI.

Je dokumentácia aj po anglicky? ​

Áno, každá stránka má anglickú verziu. Použite jazykové menu hore alebo začnite na anglickej úvodnej stránke.

Ako prejdem na 4.0? ​

Verzia 4.0 zatiaľ neexistuje; 3.x je aktuálna rada. Na GitHube je otvorený milník 4.0.0 s plánovanými nekompatibilnými zmenami, napríklad odstránením nebezpečného režimu CORS 'auto' a vyššou minimálnou verziou PHP. Dátum vydania zatiaľ nie je. Návod na upgrade pokrýva staršie hlavné verzie.