adt/api-json-router

RESTful Router for Nette with Json schema specification and verification

v2.4 2024-10-13 08:51 UTC

Requires

• php: >=8.0
• ext-json: *
• contributte/api-router: ^4.0|^5.0|^6.0
• opis/json-schema: ^2.3

Requires (Dev)

• codeception/assert-throws: ^1.2
• codeception/codeception: ^4.2
• codeception/module-asserts: ^2.0
• phpstan/phpstan: ^1.9
• slevomat/coding-standard: ^8.7

MIT

• AppsDevTeam

README

Creates a route that expects Json in request body, checks this body against Json schema supplied to the route and passes top level parameters to actions.

ApiJsonRouter extends Contributte api-router thus see the documentation for full routes definition.

Opis JSON Schema is used for full Json Schema standard validation.

Standard "draft-2020-12" is used for validation as default.

Installation

composer require adt/api-json-router

Example

Router

final class RouterFactory
{
    // Prepare your route specification
    public static function getApiRouteSpecification(): array 
    {
		return [
			'/api/devices>POST' => [
				'path' => '/api/devices/<uuid>/request',
				'presenter' => 'DeviceRequest',
				'method' => 'POST',
				'action' => 'create',
				'parameters' => [
					'uuid' => ['type' => 'string', 'requirement' => '.+'],
				],
				'body' => [
					'type' => 'object',
					'properties' => [
						'type' => ['type' => 'string'],
					],
					'required' => ['type']
				],
				'title' => 'Create a request',
				'description' => 'Create a request for a specific device.',
		    ]
	    ];
    }

    // Create API router
    public static function createRouter(): \ADT\ApiJsonRouter\ApiRouteList
    {
        $apiRouter = new \ADT\ApiJsonRouter\ApiRouteList('Api');
        $apiRouter->addRoutesBySpecification(self::getApiRouteSpecification());
        return $apiRouter;
    }
}

DeviceRequest presenter

class DeviceRequestPresenter extends Presenter 
{
    public function actionCreate(string $uuid, string $_type) 
    {
        // Check if you have access to a specific device
        if ($this->deviceQuery->create()->byUuid($uuid)) {
            $this->sendJsonError(404);
        }
    
        // Create a device request
        $deviceRequest = new DeviceRequest($device, $_type)
        $this->em->persist();
        $this->em->flush();
        
        // Send a response
        $this->sendJson(['uuid' => $deviceRequest->getUuid(), 'type' => $device->getType()]);
    }
}

Docs presenter

class DocsPresenter extends Presenter
{
	public function actionDefault()
	{
		// Generate API documentation in Markdown format
		$apiDocumentation = new ADT\ApiJsonRouter\ApiDocumentation('API Docs', RouterFactory::getApiRouteSpecification());
		$markdownApiDocumentation = $apiDocumentation->getDocumentation();

		// Generate API documentation in HTML format
		// e.g. you can use https://github.com/erusev/parsedown
		die((new \Parsedown())->text($markdownApiDocumentation));
	}
}

Error presenter

class ErrorPresenter extends Presenter
{
	public function renderDefault(Exception $exception)
	{
		if ($exception instanceof ApiException) {
		    $this->sendJsonError($exception->getCode(), $exception->getMessage());
		}

		Debugger::log($exception, ILogger::EXCEPTION);

		$this->sendJsonError(500, 'There was an error processing your request. Please try again later.');
	}
}