README

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

Installation

composer require kelemen/api-nette

Prepare to use

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']])

Api routes

Add routes to api

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')

Route patterns

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 handlers

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

Route parameters

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

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'
        ]]);
    }
}

Validations

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.

Custom validation rules

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')
}

Inputs

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.

Middleware

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

Flow and Exceptions

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

Base Implementations

Middleware

CORSMiddleware

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.

Handler

OptionsPreflightHandler

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