Príklad: hello world
Jeden endpoint, GET /api/v1/hello?name=Ada, ktorý odpovedá {"message":"Hello Ada!"}.
Handler
php
<?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'] . '!']);
}
}name je voliteľný s predvolenou hodnotou world, takže GET /api/v1/hello odpovie {"message":"Hello world!"}.
Routa
php
<?php
declare(strict_types=1);
namespace App;
use Nette\Application\Routers\RouteList;
final class RouterFactory
{
public static function create(): RouteList
{
$router = new RouteList();
// every API call goes to the presenter that ships with nette-api
$router->addRoute('/api/v<version>/<package>[/<apiAction>][/<params>]', 'Api:Api:default');
return $router;
}
}Služby
yaml
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()
)Test
bash
#!/usr/bin/env bash
# End-to-end check: start the app with the PHP built-in server and call the endpoint with curl.
set -euo pipefail
cd "$(dirname "$0")"
[[ -f vendor/autoload.php ]] || { echo "fail: vendor/ is missing, run composer install first" >&2; exit 1; }
source ../ci/lib.sh
serve 8081
request "$BASE/api/v1/hello"
expect_status 200 "GET /api/v1/hello"
expect_body '{"message":"Hello world!"}' "default name"
ok "GET /api/v1/hello says hello to the world"
request "$BASE/api/v1/hello?name=Nette"
expect_body '{"message":"Hello Nette!"}' "name from the query"
ok "GET /api/v1/hello?name=Nette uses the parameter"
request "$BASE/api/v1/nothing"
expect_status 404 "unknown endpoint"
expect_body '"Unknown api endpoint"' "unknown endpoint"
ok "an unknown endpoint answers 404"
request -X POST "$BASE/api/v1/hello"
expect_status 404 "wrong method"
ok "POST to a GET endpoint answers 404"Časté otázky
Prečo POST /api/v1/hello vracia 404?
Endpoint je zaregistrovaný len pre GET. Metóda je súčasťou endpointu, pozrite si Handlery.
Prečo DebuggerConfigurator?
Zobrazuje detaily chýb a validuje výstupy, keď je Tracy vo vývojovom režime. Pozrite si Výstupy.
Odkiaľ sa berie JSON?
JsonApiResponse zakóduje pole a nastaví Content-Type: application/json. Pozrite si Výstupy a odpovede.
Môžem pridať druhý endpoint?
Pridajte ďalší riadok addApi() s novým EndpointIdentifier. Príklad parametrov má dva.
Čo robí každý krok nastavenia?
Začíname vysvetľuje tie isté súbory krok za krokom.