, (*1)
Route automatically maps CRUD to Presenters and actions in the defined module.
And creates parameters which are accessible in Presenter., (*2)
- 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., (*3)
Installation:
The best way to install Nette-RestRoute is using Composer:, (*4)
$ composer require klapuch/nette-rest-route
Usage:
use Klapuch\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');
First parameter is a name of the module where the route will sends an Request. URL prefix will be generated. See examples., (*5)
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:, (*6)
Examples
Read all:
URL: /api/users → \ApiModule\UsersPresenter::actionReadAll
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:, (*7)
format = json
associations = array(0)
data = ""
query = array(0)
Flag readAll was dropped and Route automatically generate action readAll if no Resource ID was not found in the URL., (*8)
Read with resource ID
URL: /api/users/123 → \ApiModule\UsersPresenter::actionRead
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:, (*9)
format = json
id = 123
associations = array(0)
data = ""
query = array(0)
Query params:
URL: /api/users?foo=bar&page=1 → \ApiModule\UsersPresenter::actionReadAll
HTTP HEADER Accept: application/json
Method: GET
Request body: Empty
Params:, (*10)
format = json
associations = array(0)
data = ""
query = array(
foo => "bar"
page => 1
)
Create:
URL: /api/users → \ApiModule\UsersPresenter::actionCreate
HTTP HEADER Accept: application/json
Method: POST
Request body:, (*11)
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}
Params:, (*12)
format = json
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
Update:
URL: /api/users/123 → \ApiModule\UsersPresenter::actionUpdate
HTTP HEADER Accept: application/json
Method: PUT
Request body:, (*13)
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}
Params:, (*14)
format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
Partial update:
URL: /api/users/123 → \ApiModule\UsersPresenter::actionPartialUpdate
HTTP HEADER Accept: application/json
Method: PATCH
Request body:, (*15)
{
"foo": "bar",
"nested": {
"foo": "bar"
}
}
Params:, (*16)
format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)
Delete:
URL: /api/users/123 → \ApiModule\UsersPresenter::actionDelete
HTTP HEADER Accept: application/json
Method: DELETE
Request body: Empty
Params:, (*17)
format = json
id = 123
associations = array(0)
data = ""
query = array(0)
Options:
For more about OPTIONS documentation see w3.org., (*18)
URL: /api/users → \ApiModule\UsersPresenter::actionOptions
HTTP HEADER Accept: application/json
Method: OPTIONS
Request body: Empty
Params:, (*19)
format = json
associations = array(0)
data = ""
query = array(0)
Associations:
Last item (pair) before . is main resource. Everything what is before the last item are associations (apigee.com)., (*20)
URL: /api/users/1/comments → \ApiModule\CommentsPresenter::actionRead|actionCreate|actionUpdate|actionDelete
HTTP HEADER Accept: application/json
Method: GET, POST, PUT, DELETE
Request body: Empty
Params:, (*21)
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:, (*22)
format = json
id = 456
associations = array(
users => 123
)
data = ""
query = array(0)
URL: /api/users/1/blogs/2/comments → \ApiModule\CommentsPresenter::actionRead|actionCreate|actionUpdate|actionDelete
HTTP HEADER Accept: application/json
Method: GET, POST, PUT, DELETE
Request body: Empty
Params:, (*23)
format = json
id = 1
associations = array(
users => 1
blogs => 2
)
data = ""
query = array(0)
File uploads:
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., (*24)
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., (*25)
class FooPresenter {
/** @var \Nette\Application\Request @inject */
public $request;
public function actionCreate () {
$files = $this->request->getFiles();
}
}
Overriding methods PUT, PATCH, DELETE
Methods PUT, PATCH and DELETE can be overriden via:, (*26)
Example:, (*27)
X-HTTP-Method-Override: <PUT|PATCH|DELETE>
Query param __method
Example:, (*28)
?__method=<PUT|PATCH|DELETE>
Development
RestRoute is developed in Docker container via docker-compose command., (*29)
Example:, (*30)
$ docker-compose run --rm default install # install deps via composer
$ docker-compose run --rm default # runs tests in container
Attach to container:, (*31)
$ docker-compose run --rm default bash # runs bash in container and attach tty
Wallogit.com
