\Hazaar\Controller
REST
Abstract
The RESTful controller class

This controller can be used to create RESTful API endpoints. It automatically handles HTTP request methods and can send appropriate responses for invalid requests. It can also provide an intelligent API endpoint directory as well as allows for a simple method to version control your API.

  1. Overview Unlike other controllers, the rest controller works using annotations. Such as:

class ApiController extends \Hazaar\Controller\REST {

/** * @route(‘/dothething/‘, method=[‘GET’]) **\/ protected function do_the_thing($thingstodo){ return array(‘things’ => ‘Array of things’); }

}

This API will be accessible at the URL: http://yourhost.com/api/v1/dothething/1234

  1. Versions The version node of the URL path will always exist. If no version is specified then the version will ALWAYS be ‘v1’. Using versions allows you to easily update your API without removing backwards compatibility. New versions should be used when there is a major change to either the input or output of your endpoint and renaming it is not reasonable.

Do define another version of the above example:

class ApiController extends \Hazaar\Controller\REST {

/** * route('/dothething/<date:when>/<int:thingstodo>', method=['GET']) * version 2 **\/ protected function do_the_thing_v2($thingstodo, $when){ if($when->year() >= 2023) return array(‘things’ => ‘Array of FUTURE things’); return array(‘things’ => ‘Array of things’); }

}

This API will be accessible at the URL: http://yourhost.com/api/v1/dothething/2040-01-01/1234

  1. Endpoints on multipl versions To allow an endpoint to be available on multiple versions of your API, simply list the versions in the @version tag separated by a comma. Such as:

/** * @version 1,2 **\/

  1. Endpoint Directories Endpoint directories are simply a list of the available endpoints with some basic information about how they operate such as the HTTP method, parameter description and a brief description.

Summary
Methods Properties Constants
url
No constants
Properties
$allow_directory
$allow_directory
$describe_full
$describe_full
$endpoints
$endpoints
Inherited
$request
$request
Inherited
$statusCode
$statusCode
Methods
__describe_api()
__describe_api()
__describe_endpoint()
__describe_endpoint($route, $endpoint, $version, $describe_full = false, $api = null)

Parameters

$route

No description

$endpoint

No description

$version

No description

$describe_full

No description

$api

No description

__describe_version()
__describe_version($version)

Parameters

$version

No description

__exception()
__exception($e)

Parameters

$e\Exception

No description

__exec_endpoint()
__exec_endpoint($endpoint, $args)

Parameters

$endpoint

No description

$args

No description

__initialize()
__initialize($request)

Parameters

$request\Hazaar\Application\Request

No description

__match_route()
__match_route($path, $route, $endpoint, $args = null)

Parameters

$path

No description

$route

No description

$endpoint

No description

$args

No description

__run()
__run()
Inherited
url()
url()
Generate a URL relative to the controller

This is the controller relative method for generating URLs in your application. URLs generated from here are relative to the controller. For URLs that are relative to the current application see Application::url()

Parameters are dynamic and depend on what you are trying to generate.

For examples see: \ref generating_urls