rest-routing.md

Roteamento

Com as classes de recurso e controller prontas, você pode acessar os recursos utilizando uma URL como http://localhost/index.php?r=user/create, semelhante ao que você pode fazer com aplicações Web normais.

Na prática, normalmente você desejará utilizar URLs amigáveis e tirar proveito dos métodos HTTP. Por exemplo, uma requisição POST /users seria o mesmo que a ação user/create. Isto pode ser feito facilmente através da configuração do componente de aplicação urlManager conforme mostrado a seguir:

'urlManager' => [
   'enablePrettyUrl' => true,
   'enableStrictParsing' => true,
   'showScriptName' => false,
   'rules' => [
       ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
   ],
]

Em comparação com o gerenciamento de URL para aplicações Web, a principal novidade acima é o uso de [[yii\rest\UrlRule]] para rotear requisições API RESTful. Esta classe especial criará um conjunto de regras de URL filhas para dar suporte ao roteamento e a criação de URL para o controller especificado. Por exemplo, o código acima é mais ou menos equivalente às seguintes regras:

[
   'PUT,PATCH users/<id>' => 'user/update',
   'DELETE users/<id>' => 'user/delete',
   'GET,HEAD users/<id>' => 'user/view',
   'POST users' => 'user/create',
   'GET,HEAD users' => 'user/index',
   'users/<id>' => 'user/options',
   'users' => 'user/options',
]

E as seguintes URLs (também chamadas de endpoints) da API são suportados por esta regra:

• GET /users: lista todos os usuários página por página;
• HEAD /users: mostrar a informações gerais da listagem de usuários;
• POST /users: cria um novo usuário;
• GET /users/123: retorna detalhes do usuário 123;
• HEAD /users/123: mostrar a informações gerais do usuário 123;
• PATCH /users/123 and PUT /users/123: atualiza o usuário 123;
• DELETE /users/123: deleta o usuário 123;
• OPTIONS /users: exibe os métodos suportados pela URL /users;
• OPTIONS /users/123: exibe os métodos suportados pela URL /users/123.

Você pode configurar as opções only e except para listar explicitamente quais ações são suportadas ou quais ações devem ser desativadas, respectivamente. Por exemplo,

[
   'class' => 'yii\rest\UrlRule',
   'controller' => 'user',
   'except' => ['delete', 'create', 'update'],
],

Você também pode configurar patterns ou extraPatterns para redefinir padrões existentes ou adicionar novos padrões suportados por esta regra. Por exemplo, para acessar a uma nova ação search pela URL GET /users/search, configure a opção extraPatterns como a seguir,

[
   'class' => 'yii\rest\UrlRule',
   'controller' => 'user',
   'extraPatterns' => [
       'GET search' => 'search',
   ],
]

Você deve ter notado que o ID user de controller aparece no plural como users na extremidade das URLs. Isto acontece porque [[yii\rest\UrlRule]] pluraliza os IDs de controllers automaticamente na criação de regras de URLs filhas. Você pode desabilitar este comportamento configurando [[yii\rest\UrlRule::pluralize]] para false.

Observação: A pluralização dos IDs de controllers são feitas pelo método [[yii\helpers\Inflector::pluralize()]]. O método respeita as regras especiais de pluralização. Por exemplo, a palavra box será pluralizada para boxes em vez de boxs.

Caso a pluralização automática não encontre uma opção para a palavra requerida, você pode configurar a propriedade [[yii\rest\UrlRule::controller]] para especificar explicitamente como mapear um nome para ser usado como uma URL para um ID de controller. Por exemplo, o seguinte código mapeia o nome u para o ID user de controller.

[
   'class' => 'yii\rest\UrlRule',
   'controller' => ['u' => 'user'],
]