Example: DI extension

Q: How do I run it?

composer install and ./e2e.sh in examples/di-extension. The test starts the PHP built-in server on port 8097.

Q: Where is the ApiPresenter registered?

The extension registers it as api.presenter. The application: mapping and the route in RouterFactory are still in the application.

Q: How do I add an endpoint?

Write the handler in app/Api/ and add one line to api: endpoints:. Nothing else changes.

Q: Can I use it with the services from the other examples?

Yes, an ApiDecider or error handler in services: is used instead of the extension's one, see Moving from services.

A users API configured only in the api: section of config/common.neon, with the DI extension. There is no ApiDecider, ApiPresenter or error handler in services:.

Since 4.0.0

NetteApiExtension is new in 4.0.0.

Request	Status	Note
`GET /api/v1/hello`	`200`	public, `authorization: false`
`GET /api/v1/users` without a token	`401`	the default authorization, as a problem detail
`GET /api/v1/users` with `Authorization: Bearer secret-token`	`200`	the list from `UserRepository`
`GET /api/v1/users/detail?id=2`	`200`	`action: detail`
`GET /api/v1/users/detail`	`400`	`type` `https://api.example.com/problems/validation-error`
`POST /api/v1/users` `name=Carol`	`201`, `201`, then `429`	`rateLimit: strict`, 2 requests per minute
`OPTIONS /api/v1/users`	`200`	preflight, no token needed
`GET /api/v1/nothing`	`404`	`type` `https://api.example.com/problems/not-found`

The configuration

yaml

extensions:
	api: Tomaj\NetteApi\DI\NetteApiExtension

parameters:
	apiTokens:
		secret-token: '*'

services:
	router: App\RouterFactory::create
	# a normal application service, handlers get it through autowiring
	- App\Model\UserRepository

api:
	# error details are on unless APP_ENV=production
	outputConfigurator: Tomaj\NetteApi\Output\Configurator\EnvConfigurator('APP_ENV', 'production')

	errors:
		format: problemDetails
		typeBaseUri: https://api.example.com/problems/

	# without cors the extension sends no CORS headers
	cors:
		allowedOrigins: [https://app.example.com]
		preflight: true

	logging:
		maskHeaders: true

	# named services, endpoints use them by name
	authorizations:
		token: Tomaj\NetteApi\Authorization\BearerTokenAuthorization(Tomaj\NetteApi\Misc\StaticTokenRepository(%apiTokens%))
	rateLimits:
		strict: App\FileRateLimit(storageDir: %tempDir%, limit: 2)

	# every endpoint needs the token unless it says otherwise
	defaults:
		authorization: token

	endpoints:
		# GET /api/v1/hello is public
		- {method: GET, version: 1, package: hello, handler: App\Api\HelloHandler('Hello from neon'), authorization: false}
		# GET /api/v1/users and GET /api/v1/users/detail?id=1 need the token
		- {method: GET, version: 1, package: users, handler: App\Api\UsersListHandler}
		- {method: GET, version: 1, package: users, action: detail, handler: App\Api\UserDetailHandler}
		# POST /api/v1/users is limited to 2 calls per minute
		- {method: POST, version: 1, package: users, handler: App\Api\UserCreateHandler, rateLimit: strict}

defaults: authorization: token protects every endpoint, authorization: false makes hello public.
HelloHandler('Hello from neon') is a statement, the handler gets its argument from the config.
UsersListHandler gets UserRepository from its constructor by autowiring.

A handler with a dependency

php

<?php

declare(strict_types=1);

namespace App\Api;

use App\Model\UserRepository;
use Tomaj\NetteApi\Handlers\BaseHandler;
use Tomaj\NetteApi\Response\JsonApiResponse;
use Tomaj\NetteApi\Response\ResponseInterface;

final class UsersListHandler extends BaseHandler
{
    // UserRepository is autowired, the handler is a normal service
    public function __construct(private readonly UserRepository $users)
    {
        parent::__construct();
    }

    public function handle(array $params): ResponseInterface
    {
        return new JsonApiResponse(200, ['users' => $this->users->all()]);
    }
}

The rate limit

php

<?php

declare(strict_types=1);

namespace App;

use Nette\Http\IRequest;
use Tomaj\NetteApi\RateLimit\RateLimitInterface;
use Tomaj\NetteApi\RateLimit\RateLimitResponse;

/**
 * Fixed window: at most $limit requests per client in $window seconds.
 * Counts in files to stay runnable without Redis; use Redis or APCu in production.
 */
final class FileRateLimit implements RateLimitInterface
{
    public function __construct(
        private IRequest $request,
        private string $storageDir,
        private int $limit = 2,
        private int $window = 60,
    ) {
    }

    public function check(): ?RateLimitResponse
    {
        // runs before authorization, so the key cannot be trusted yet; it only picks the bucket
        $client = $this->request->getHeader('X-Api-Key') ?? $this->request->getRemoteAddress() ?? 'unknown';
        $windowStart = intdiv(time(), $this->window) * $this->window;
        $file = $this->storageDir . '/rate-' . sha1($client) . '-' . $windowStart;

        $handle = fopen($file, 'c+');
        flock($handle, LOCK_EX);
        $usedBefore = (int) stream_get_contents($handle);
        if ($usedBefore < $this->limit) {
            ftruncate($handle, 0);
            rewind($handle);
            fwrite($handle, (string) ($usedBefore + 1));
        }
        flock($handle, LOCK_UN);
        fclose($handle);

        $retryAfter = $windowStart + $this->window - time();

        // ApiPresenter answers 429 when remaining is 0, so remaining counts this request too:
        // with limit 2 the first two requests get 2 and 1, the third one gets 0 and a 429 problem
        return new RateLimitResponse(
            $this->limit,
            $this->limit - min($usedBefore, $this->limit),
            $retryAfter,
        );
    }
}

The bootstrap

php

<?php

declare(strict_types=1);

namespace App;

use Nette\Bootstrap\Configurator;
use Nette\Utils\FileSystem;

final class Bootstrap
{
    public static function boot(): Configurator
    {
        $configurator = new Configurator();
        FileSystem::createDir(__DIR__ . '/../log');
        $configurator->enableTracy(__DIR__ . '/../log');
        $configurator->setTempDirectory(__DIR__ . '/../temp');
        $configurator->addConfig(__DIR__ . '/../config/common.neon');
        return $configurator;
    }
}

The test

bash

#!/usr/bin/env bash
# End-to-end check: the whole API is configured in the "api:" neon section of the DI extension.
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
rm -rf temp/cache temp/rate-* log
serve 8097
P='https://api.example.com/problems/'

request "$BASE/api/v1/hello"
expect_status 200 "public endpoint"
expect_body '{"message":"Hello from neon"}' "statement argument"
ok "GET /api/v1/hello is public and the handler got its neon argument"

request "$BASE/api/v1/users"
expect_status 401 "default authorization"
expect_header 'Content-Type: application/problem+json' "errors.format"
expect_body "\"type\":\"${P}unauthorized\"" "errors.typeBaseUri"
ok "defaults.authorization protects GET /api/v1/users, the error is a problem detail"

request -H 'Authorization: Bearer secret-token' "$BASE/api/v1/users"
expect_status 200 "token"
expect_body '{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}' "autowired repository"
ok "with the token the handler answers with users from an autowired service"

request -H 'Authorization: Bearer secret-token' "$BASE/api/v1/users/detail?id=2"
expect_status 200 "action"
expect_body '{"id":2,"name":"Bob"}' "detail"
ok "GET /api/v1/users/detail is a separate endpoint (action: detail)"

request -H 'Authorization: Bearer secret-token' "$BASE/api/v1/users/detail"
expect_status 400 "params"
expect_body "\"type\":\"${P}validation-error\"" "validation problem"
ok "a missing param answers 400 problem"

request -H 'Origin: https://app.example.com' "$BASE/api/v1/hello"
expect_header 'Access-Control-Allow-Origin: https://app.example.com' "allowed origin"
request -H 'Origin: https://evil.example.com' "$BASE/api/v1/hello"
no_header 'Access-Control-Allow-Origin' "other origin"
ok "cors.allowedOrigins answers only the listed origin"

request -X OPTIONS -H 'Origin: https://app.example.com' "$BASE/api/v1/users"
expect_status 200 "preflight"
expect_header 'Access-Control-Allow-Methods' "preflight methods"
ok "cors.preflight answers OPTIONS for every endpoint without a token"

for i in 1 2; do
    request -X POST -H 'Authorization: Bearer secret-token' -d 'name=Carol' "$BASE/api/v1/users"
    expect_status 201 "create $i"
done
expect_body '{"id":3,"name":"Carol"}' "created"
request -X POST -H 'Authorization: Bearer secret-token' -d 'name=Carol' "$BASE/api/v1/users"
expect_status 429 "rate limit"
expect_body "\"type\":\"${P}rate-limited\"" "429 problem"
ok "rateLimit: strict lets 2 POST requests through, the third one gets 429"

request "$BASE/api/v1/nothing"
expect_status 404 "unknown"
expect_body "\"type\":\"${P}not-found\"" "404 problem"
ok "an unknown endpoint answers 404 problem"

# the compiled container only calls addApi(), the handlers are created when they are used
grep -q "addApi" temp/cache/nette.configurator/*.php || { echo "fail: no addApi() in the compiled container" >&2; exit 1; }
ok "the compiled container registers the endpoints with addApi()"

FAQ

How do I run it?

composer install and ./e2e.sh in examples/di-extension. The test starts the PHP built-in server on port 8097.

Where is the ApiPresenter registered?

The extension registers it as api.presenter. The application: mapping and the route in RouterFactory are still in the application.

How do I add an endpoint?

Write the handler in app/Api/ and add one line to api: endpoints:. Nothing else changes.

What happens with a typo in the config?

The container does not compile, and the message names the endpoint and the key. Try authorization: tokne.

Can I use it with the services from the other examples?

Yes, an ApiDecider or error handler in services: is used instead of the extension's one, see Moving from services.

Example: DI extension ​

The configuration ​

A handler with a dependency ​

The rate limit ​

The bootstrap ​

The test ​

FAQ ​

How do I run it? ​

Where is the ApiPresenter registered? ​

How do I add an endpoint? ​

What happens with a typo in the config? ​

Can I use it with the services from the other examples? ​