kelemen / api-nette
Api for Nette framework
Installs: 1 852
Dependents: 0
Suggesters: 0
Security: 0
Stars: 18
Watchers: 4
Forks: 3
Open Issues: 3
Requires
- php: >= 5.6
Requires (Dev)
- nette/nette: ~2.4
- phpunit/phpunit: ^5.3
- squizlabs/php_codesniffer: ^2.6
README
Highly customizable and easy to setup REST api handling for Nette framework.
Installation
composer require kelemen/api-nette
Prepare to use
-
First of all you need an Api presenter for handle api requests. You can use
Kelemen\ApiNette\Presenter\ApiPresenter
or write you own. -
Register new mapping in config.neon
application: mapping: Api: Kelemen\ApiNette\Presenter\*Presenter
-
Add api route to router. We use keyword api for identify api requests.
$router[] = new Route("api/<params .*>", [ 'presenter' => 'Api', 'action' => 'default' ]);
-
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