REST route for Nette Framework
Route automatically maps CRUD to Presenters and actions in the defined module. And creates parameters which are accessible in Presenter.
- format
- id (autodetected)
- associations (an array with associations)
- data (raw data from the request)
- query (an array of items from the query string)
Variable $format is detected from HTTP header Accept. If header is not present Route try detect format from the URL (.../foo.json). If no format is in the URL Route use a default format json.
The best way to install Nette-RestRoute is using Composer:
$ composer require adamstipak/nette-rest-routeuse AdamStipak\RestRoute;
// $router is an instance of Nette\Application\Routers\RouteList
// No parameters needed. Presenter name will be generated.
$router[] = new RestRoute;
// With module.
$router[] = new RestRoute('Api');
// With module and xml as a default format.
$router[] = new RestRoute('Api', 'xml');
// With URL module versioning
$router[] = (new RestRoute())
->useURLModuleVersioning(
'/v[0-9\.]+/', // Regex for URL version
[ // URL fragment to module mapping
NULL => 'V1', // Default version module is V1
'v1' => 'V1', // /v1 to module V1
'v2' => 'V2' // /v2 to module V2
]
);First parameter is a name of the module where the route will sends an Request. URL prefix will be generated. See examples. ####Examples:
NULL => /<generated presenter name>
'Api' => /api/<generated presenter name>
'My:Api' => /my/api/<generated presenter name>
...
Second parameter is default format. By default the default format is json.
RestRoute support only 2 formats:
- json (default)
- xml
URL: /api/users → \ApiModule\UsersPresenter::actionReadAll
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:
format = json
associations = array(0)
data = ""
query = array(0)
Flag
readAllwas dropped andRouteautomatically generate actionreadAllif no Resource ID was not found in the URL.
URL: /api/users/123 → \ApiModule\UsersPresenter::actionRead
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:
format = json
id = 123
associations = array(0)
data = ""
query = array(0)
URL: /api/users?foo=bar&page=1 → \ApiModule\UsersPresenter::actionReadAll
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:
format = json
associations = array(0)
data = ""
query = array(
foo => "bar"
page => 1
)
URL: /api/users → \ApiModule\UsersPresenter::actionCreate
HTTP HEADER Accept: application/json
Method: POST
Request body:
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}Params:
format = json
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
URL: /api/users/123 → \ApiModule\UsersPresenter::actionUpdate
HTTP HEADER Accept: application/json
Method: PUT
Request body:
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}Params:
format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
URL: /api/users/123 → \ApiModule\UsersPresenter::actionPartialUpdate
HTTP HEADER Accept: application/json
Method: PATCH
Request body:
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}Params:
format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
URL: /api/users/123 → \ApiModule\UsersPresenter::actionDelete
HTTP HEADER Accept: application/json
Method: DELETE
Request body: Empty
Params:
format = json
id = 123
associations = array(0)
data = ""
query = array(0)
For more about OPTIONS documentation see w3.org.
URL: /api/users → \ApiModule\UsersPresenter::actionOptions
HTTP HEADER Accept: application/json
Method: OPTIONS
Request body: Empty
Params:
format = json
associations = array(0)
data = ""
query = array(0)
Last item (pair) before . is main resource. Everything what is before the last item are associations (apigee.com).
URL: /api/users/1/comments → \ApiModule\CommentsPresenter::actionReadAll|actionCreate|actionUpdate|actionDelete
HTTP HEADER Accept: application/json
Method: GET, POST, PUT, DELETE
Request body: Empty
Params:
format = json
associations = array(
users => 1
)
data = ""
query = array(0)
URL: /api/users/123/comments/456 → \ApiModule\CommentsPresenter::actionRead|actionCreate|actionUpdate|actionDelete
HTTP HEADER Accept: application/json
Method: GET, POST, PUT, DELETE
Request body: Empty
Params:
format = json
id = 456
associations = array(
users => 123
)
data = ""
query = array(0)
URL: /api/users/1/blogs/2/comments → \ApiModule\CommentsPresenter::actionReadAll|actionCreate|actionUpdate|actionDelete
HTTP HEADER Accept: application/json
Method: GET, POST, PUT, DELETE
Request body: Empty
Params:
format = json
id = 1
associations = array(
users => 1
blogs => 2
)
data = ""
query = array(0)
RestRoute provides you with option to version your API in URL. Each version is represented by separate module in your application.
First, you define regexp which is used to detect if the version parameter is present in URL. It must be in the begging of the path.
Then, you define version to module mapping. NULL key stands for default module, if version parameter doesn't get detected.
$router[] = (new RestRoute('Api')) // Optional module
->useURLModuleVersioning(
RestRoute::MODULE_VERSION_PATH_PREFIX_PATTERN, // Regex for URL version
[ // URL fragment to module mapping
NULL => 'V1', // Default version module is V1
'v1' => 'V1', // /v1 to module V1
'v2' => 'V2' // /v2 to module V2
]
);RestRoute will now map your requests to presenters like this (URL -> Presenter):
/api/foo -> Api:V1:Foo
/api/v1/foo -> Api:V1:Foo
/api/v2/foo -> Api:V2:Foo
RestRoute reads standard PHP input and data puts to $data param in action. This is fit for one file upload or upload with chunks because it is a RAW data.
For multiple file upload RestRoute just set files when creates \Nette\Application\Request. In presenter just inject \Nette\Application\Request service and use these files.
class FooPresenter {
/** @var \Nette\Application\Request @inject */
public $request;
public function actionCreate () {
$files = $this->request->getFiles();
}
}RestRoute is developed in Docker container via docker-compose command.
Example:
$ docker-compose run --rm default install # install deps via composer
$ docker-compose run --rm default # runs tests in containerAttach to container:
$ docker-compose run --rm default bash # runs bash in container and attach tty
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent