Controladores

Después de crear las clases de recursos y especificar cómo debe ser el formato de datos de recursos, el siguiente paso es crear acciones del controlador para exponer los recursos a los usuarios a través de las APIs RESTful finales.

Yii ofrece dos clases de controlador base para simplificar su trabajo de crear acciones REST: yii\rest\Controller y yii\rest\ActiveController. La diferencia entre estos dos controladores es que este último proporciona un conjunto predeterminado de acciones que están específicamente diseñadas para hacer frente a los recursos representados con Active Record. Así que si usted está utilizando Active Record y se siente cómodo con las acciones integradas que proporciona, es posible considerar la prolongación de sus clases de controlador de yii\rest\ActiveController, que le permitirá crear potentes APIs RESTful con un mínimo de código.

Ambos yii\rest\Controller y yii\rest\ActiveController proporcionan las siguientes características, algunas de las cuales se describen en detalle en las siguientes secciones:

Métodos de Validación HTTP;
Negociación de contenido y formato de datos;
Autenticación;
Límite de Rango.

yii\rest\ActiveController además provee de las siguientes características:

Un conjunto de acciones comunes necesarias: index, view, create, update, delete, options;
La autorización del usuario en cuanto a la acción solicitada y recursos.

Creando Clases Controladoras

Al crear una nueva clase de controlador, una convención para nombrar la clase del controlador es utilizar el nombre del tipo de recurso y el uso en singular. Por ejemplo, para servir información de usuario, el controlador puede ser nombrado como UserController.

Creación de una nueva acción es similar a crear una acción para una aplicación Web. La única diferencia es que en lugar de hacer que el resultado utilicé una vista llamando al método render(), para las acciones REST regresá directamente los datos. El yii\rest\Controller::serializer y el yii\web\Response se encargará de la conversión de los datos originales al formato solicitado. Por ejemplo,

public function actionView($id)
{
    return User::findOne($id);
}

Filtros

La mayoría de las características API REST son proporcionadas por yii\rest\Controller que son implementadas por los terminos de los filtros. En particular, los siguientes filtros se ejecutarán en el orden en que aparecen:

yii\filters\ContentNegotiator: apoya la negociación de contenido, que se explica en la sección el Formateo de respuestas;
yii\filters\VerbFilter: apoya métodos de validación HTTP;
yii\filters\AuthMethod: apoya autenticación de usuarios, que se explica en la sección Autenticación;
yii\filters\RateLimiter: apoya la limitación de rango, que se explica en la sección Límite de Rango.

Estos filtros se declaran nombrándolos en el método yii\rest\Controller::behaviors(). Puede reemplazar este método para configurar los filtros individuales, desactivar algunos de ellos o añadir sus propios filtros. Por ejemplo, si sólo desea utilizar la autenticación básica HTTP, puede escribir el siguiente código:

use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => HttpBasicAuth::className(),
    ];
    return $behaviors;
}

Extendiendo `ActiveController`

Si su clase controlador extiende de yii\rest\ActiveController, debe establecer su propiedad yii\rest\ActiveController::modelClass a ser el nombre del recurso de la clase que va a servir a través de este controlador. La clase debe extender de yii\db\ActiveRecord.

Personalizando Acciones

Por defecto, yii\rest\ActiveController provee de las siguientes acciones:

yii\rest\IndexAction: lista de recursos pagina por pagina;
yii\rest\ViewAction: retorna el detalle de un recurso específico;
yii\rest\CreateAction: crear un nuevo recurso;
yii\rest\UpdateAction: actualizar un recurso existente;
yii\rest\DeleteAction: eliminar un recurso específico;
yii\rest\OptionsAction: retorna los métodos HTTP soportados.

Todas esta acciones se declaran a través del métodos yii\rest\ActiveController::actions(). Usted puede configurar todas estas acciones o desactivar alguna de ellas reescribiendo el método actions(), como se muestra a continuación,

public function actions()
{
    $actions = parent::actions();

    // disable the "delete" and "create" actions
    unset($actions['delete'], $actions['create']);

    // customize the data provider preparation with the "prepareDataProvider()" method
    $actions['index']['prepareDataProvider'] = [$this, 'prepareDataProvider'];

    return $actions;
}

public function prepareDataProvider()
{
    // prepare and return a data provider for the "index" action
}

Por favor, consulte las referencias de clases para la clase de acción individuales para aprender las opciones de configuración que se dispone.

Realizando Comprobación de Acceso

Al exponer los recursos a través de RESTful APIs, a menudo es necesario comprobar si el usuario actual tiene permiso para acceder y manipular el recurso solicitado. Con yii\rest\ActiveController, puede hacerse reemplazando el método yii\rest\ActiveController::checkAccess() con lo siguiente,

/**
 * Checks the privilege of the current user.
 *
 * This method should be overridden to check whether the current user has the privilege
 * to run the specified action against the specified data model.
 * If the user does not have access, a [[ForbiddenHttpException]] should be thrown.
 *
 * @param string $action the ID of the action to be executed
 * @param \yii\base\Model $model the model to be accessed. If null, it means no specific model is being accessed.
 * @param array $params additional parameters
 * @throws ForbiddenHttpException if the user does not have access
 */
public function checkAccess($action, $model = null, $params = [])
{
    // check if the user can access $action and $model
    // throw ForbiddenHttpException if access should be denied
}

El método checkAccess() será llamado por defecto en las acciones predeterminadas de yii\rest\ActiveController. Si crea nuevas acciones y también desea llevar a cabo la comprobación de acceso, debe llamar a este método de forma explícita en las nuevas acciones.

Consejo: Usted puede implementar checkAccess() mediante el uso del Componente Role-Based Access Control (RBAC).

7.1 KiB Raw Blame History