.docs

Contributte / ApiRouter

Content

• Installation
• Usage
  • Using attributes
  • Using Nette Router
  • Api documentation
• Examples

Installation

ApiRouter is available on composer:

composer require contributte/api-router

Usage

Configure

At first register compiler extension.

extensions:
	apiRouter: Contributte\ApiRouter\DI\ApiRouterExtension

Don't forget to register your controller/presenter/endpoint classes.

services:
	- App\Controllers\LoginController
	- App\Controllers\PingController

Using attributes

Example of used attributes. Don't forget to import Contributte\ApiRouter\ApiRoute.

namespace App\ResourcesModule\Presenters;

use Nette\Application\UI\Presenter;
use Contributte\ApiRouter\ApiRoute;

/**
 * API for managing users
 */
#[ApiRoute(
	path: '/api-router/api/users[/<id>]',
	parameters: [
		'id' => [
			'requirement' => '\d+',
			'default' => 10,
		],
	],
	priority: 1,
	presenter: 'Resources:Users',
)]
class UsersController extends Presenter
{

	/**
	 * Get user detail
	 */
	#[ApiRoute(
		path: '/api-router/api/users/<id>[/<foo>-<bar>]',
		parameters: [
			'id' => [
				'requirement' => '\d+',
			],
		],
		method: 'GET',
	)]
	public function actionRead(int $id, ?string $foo = null, ?string $bar = null): void
	{
		$this->sendJson(['id' => $id, 'foo' => $foo, 'bar' => $bar]);
	}


	public function actionUpdate(int $id): void
	{
		$this->sendJson(['id' => $id]);
	}


	public function actionDelete(int $id): void
	{
		$this->sendJson(['id' => $id]);
	}
}

Now 3 routes will be created (well, 2, but the one accepts both PUT and DELETE method).

If you don't want to create route with DELETE method, simply remove the UsersPresenter::actionDelete() method.

Using Nette Router

namespace App;

use Contributte\ApiRouter\ApiRoute;
use Nette;
use Nette\Application\Routers\Route;
use Nette\Application\Routers\RouteList;

class RouterFactory
{

	public function createRouter(): Nette\Routing\RouteList
	{
		$router = new RouteList;

		/**
		 * Simple route with matching (only if methods below exist):
		 * 	GET     => UsersPresenter::actionRead()
		 * 	POST    => UsersPresenter::actionCreate()
		 * 	PUT     => UsersPresenter::actionUpdate()
		 * 	DELETE  => UsersPresenter::actionDelete()
		 */
		$router[] = new ApiRoute(path: '/hello', presenter: 'Users');

		/**
		 * Custom matching:
		 * 	GET  => UsersPresenter::actionSuperRead()
		 * 	POST => UsersPresenter::actionCreate()
		 */
		$router[] = new ApiRoute(path: '/hello', presenter: 'ApiRouter', methods: ['GET' => 'superRead', 'POST']);

		$router[] = new ApiRoute(
			path: '/api-router/api/users[/<id>]',
			presenter: 'Resources:Users',
			parameters: [
				'id' => ['requirement' => '\d+', 'default' => 10],
			],
			priority: 1,
		);

		$router[] = new ApiRoute(
			path: '/api-router/api/users/<id>[/<foo>-<bar>]',
			presenter: 'Resources:Users',
			parameters: [
				'id' => ['requirement' => '\d+'],
			],
			priority: 1,
		);

		# Disable basePath detection
		$route = new ApiRoute(path: '/api-router/api/users', presenter: 'Resources:Users');
		$route->setAutoBasePath(false);
		$router[] = $route;

		$router[] = new Route('<presenter>/<action>', 'Homepage:default');

		return $router;
	}
}

Api documentation

There is another extension for Nette which works pretty well with ApiRouter: ApiDocu. ApiDocu generates awesome api documentation from your RESTful routes. It can also show you documentation in application runtime!

Examples

We've made a few skeleton with preconfigured contributte/api-router.

https://github.com/contributte/api-router-skeleton