Highly customizable and easy to setup REST api handling for Nette framework.

composer require kelemen/api-nette

1. First of all you need an Api presenter for handle api requests. You can use Kelemen\ApiNette\Presenter\ApiPresenter or write you own.

2. Register new mapping in config.neon

   application:
       mapping:
           Api: Kelemen\ApiNette\Presenter\*Presenter

3. Add api route to router. We use keyword api for identify api requests.

   $router[] = new Route("api/<params .*>", [
       'presenter' => 'Api',
       'action' => 'default'   
   ]);

4. Configure Api (example from config.neon)

   services:
       - Kelemen\ApiNette\Logger\Storage\DummyLoggerStorage
       - Kelemen\ApiNette\Logger\Logger
       api:
           class: Kelemen\ApiNette\Api
           setup:
               - get('users', 'Custom\Users\ListHandler')
               - get('users/<id>', 'Custom\Users\DetailHandler')
               - put('users/<id>', 'Custom\Users\CrateHandler', [middleware: ['Custom\Auth\Bearer'])
               - post('users/<id>', 'Custom\Users\UpdateHandler', [middleware: ['Custom\Auth\Bearer']])

REST api routes can be defined with shortcut functions (for most used HTTP methods):

• get
• post
• put
• patch
• delete
• options

Or you can add any HTTP method processing with add($method, $pattern, $handler, $params = []) function.

$api = new Api(...);
$api->add('purge', 'purge/urls', 'Handlers\PurgeHandler')

In route definition you can use regular patterns or define parameters closed in < and >. Routes are evaluated in order they was added. So define specific routes first.

$api = new Api(...);
$api->get('users', 'Handler');         // exact match for (with our route) /api/users
$api->get('users/<id>', 'Handler');    // parse parameter id from routes like /api/users/10, /api/users/sdk-2323 etc.
$api->get('users/<id>/message/<messageId>', 'Handler'); // parse parameters id and messageId from matched requests

// Optional parameters are not supported. If optional parameter is needed we have to define multiple routes.
$api->get('users/<id>/message', 'Handler');
$api->get('users/<id>/message/<messageId>', 'Handler');

// In route definition we can use any regular expression.
$api->options('.*', 'Handler');          // process OPTIONS call for any incoming URL

Route definition use lazy loading from Nette DI Container. Handlers are defined by type or by name registered in config.neon file. For name definition, prefix service name with #.

$api = new Api(...);
$api->get('users', 'Full\Namespace\For\Handler');       // By type
$api->get('users/<id>', '#registeredHandlerName');      // By name

As parameter is now accepted only middleware key. Middleware definition use same lazy loading logic as handlers.

$api = new Api(...);
$api->get('users', 'Full\Namespace\For\Handler', ['middleware' => [
    'Middleware\Auth\Bearer',   // By type
    '#bearerAuthorization'      // By name
]]);

Handler provide business logic for resolved api route.

use Nette\Http\Request;
use Nette\Http\Response;
use Kelemen\ApiNette\Handler\BaseHandler;
use Kelemen\ApiNette\Response\JsonApiResponse;
use Kelemen\ApiNette\Validator\Validation;

class UserGetHandler extends BaseHandler
{
    // Here we can define validation rules for input parameters (see section Validations below).
    // This function is optional.
    public function validate()
    {
        return [
            new Validation('path', 'id', 'required|integer'),
            new Validation('get', 'page', 'integer:1..100')
        ];
    }

    // Main function. Process request and return ApiResponse.
    public function __invoke(Request $request, Response $response, callable $next)
    {
        // ... do some business logic as filtering, database requests etc.
        
        // All validated values are acessible via $this->values array
        $id = $this->values['id'];
        if ($id && isset($this->values['page'])) {
            ...
        }
        
        return new JsonApiResponse(200, ['data' => [
            'id' => 1,
            'name' => 'Samuel'
        ]]);
    }
}

IMPORTANT! Every parameter is parsed as string! So use numeric validation rule instead of integer or float.

Primary validation is handled by Nette Validators. Validations are registered in handlers validate() function. All validated input parameters are accessible in handler via $this->values array.

If any validation failed, api automatically send response with 400 HTTP code with all validation errors.

By default you don't need to register new Validator instance to Api. But if you want register new validations or override existing validations you need to create and configure your own Validator instance.

$validator = new Kelemen\ApiNette\Validator\Validator();
$validator->setValidator('enum', function ($value, $ruleParams = null) {
    // $value - contains parameter value
    // $ruleParams - contains string from parsed rule after ":"
    return in_array($value, explode(',', $ruleParams));
});

// Usage in validation funciton ...

public function validate()
{
    return new Validation('get', 'name', 'required|enum:Samuel,Peter')
}

Validator has defined set of default inputs

If you want some special input you can add this input to Validator with setInput($name, InputInterface $input) function.

Api flow can be extended by middleware. Middleware interface has only one function __invoke(Request $request, Response $response, callable $next). How middleware works:

use Kelemen\ApiNette\Middleware\Middleware;
use Nette\Http\Request;
use Nette\Http\Response;

class CustomMiddleware implements Middleware
{
    public function __invoke(Request $request, Response $response, callable $next)
    {
        // This code is executed before handler (Optional)
        // Example: provide authentification here. If user is authenticated call $next() if no return new response
        if ($request->isSecured()) {
            // Do something ...
        }

        // Call next middleware or handler if last middleware (Optional)
        $resp = $next($request, $response);

        // This code is executed after handler (Optional)
        // Example: add CORS headers here
        $response->setHeader('custom header', 'header value');

        // Mandatory! Every middleware has to return response!
        return $resp;
    }

}

If we have 3 middlewares registered as

['middleware1', 'middleware2', 'middleware3']

Flow will look like:

- middleware1
    - middleware2
        - middleware3
            - handler (return Nette\Application\IResponse)
        - middleware3
    - middleware2
- middleware1

Library is shipped with default api presenter Kelemen\ApiNette\Presenter\ApiPresenter. This presenter running api and handle all exceptions (create response depends on catched exception). If you want custom error responses, create and register your own presenter.

Api throws this exceptions

Setup Access-Control-Allow-Origin and Access-Control-Allow-Credentials headers. Middleware has 3 modes:

• all - returns allow-origin as "*". Credentials header is disabled by standard.
• mirror - returns request header "Origin" in allow-origin and credentials header can be configured manually.
• custom - allow-origin header has to be configured and credentials header can be configured manually.

Configurable handler for browser CORS preflight request. Configurable response headers:

• Access-Control-Max-Age
• Access-Control-Expose-Headers
• Access-Control-Allow-Methods
• Access-Control-Allow-Headers