SIU-Guarani/Version3.20.0/personalizaciones/rest

Personalizar servicios REST

Crear un nuevo servicio REST

Si lo que se desea es crear un nuevo servicio REST se debe hacer lo siguiente:

Supongamos que el nuevo servicio manipule aulas, por lo tanto nuestro nuevo recurso pasara a llamarse aulas, para crearlo seguiremos los siguientes pasos:

1. Crear el archivo <path proyecto Guaraní>/personalizacion/php/rest/v1/aulas_uni/recurso_aulas_uni.php, donde uni sera en nombre de la universidad en cuestión (esto evita futuras colisiones de nombre si el SIU decide mas adelante agregar el recurso aulas).
2. Dentro de dicho archivo crear la clase recurso_aulas_uni la cual debe implementar la interface modelable:

   <?php
   
   //personalizacion/php/rest/v1/aulas_uni/recurso_aulas_uni.php
   
   namespace PERS\Guarani\php\rest\v1\aulas_uni;
   
   use SIUToba\rest\rest;
   use SIUToba\rest\lib\rest_validador;
   use SIUToba\rest\lib\modelable;
   
   class recurso_aulas_uni implements modelable{
       ............
   }

3. Luego procederemos a agregar la capa de datos que se encargara de las operaciones de tipo ABM/CRUD de los servicios en cuestión, en este caso agregaremos la clase rest_aulas_uni en <path proyecto Guaraní>/personalizacion/php/rest/v1/modelos/rest_aulas_uni.php:

   <?php
   
   //personalizacion/php/rest/v1/modelos/rest_aulas_uni.php
   
   namespace PERS\Guarani\php\rest\v1\modelos;
   
   class rest_aulas_uni{
   
           function post($datos){
                   // Guardar aula en la DB
           }
          
           function get_list(){
                   return [
                           [
                                   'nombre' => 'Aula ejemplo 1',
                                   'fecha_creacion' => '2012-09-25',
                                   'estado' => 'A',
                                   'edificio' => [
                                           'nombre' => 'Edificio ejemplo 1'
                                   ]
                           ],
                           [
                                   'nombre' => 'Aula ejemplo 2',
                                   'fecha_creacion' => '2012-09-25',
                                   'estado' => 'B',
                                   'edificio' => [
                                           'nombre' => 'Edificio ejemplo 2'
                                   ]
                           ],
                           [
                                   'nombre' => 'Aula ejemplo 3',
                                   'fecha_creacion' => '2012-09-25',
                                   'estado' => 'A',
                                   'edificio' => [
                                           'nombre' => 'Edificio ejemplo 3'
                                   ]
                           ]
                   ];
           }
          
           function get(){
                   return [
                                   'nombre' => 'Aula ejemplo 1',
                                   'fecha_creacion' => '2012-09-25',
                                   'estado' => 'A',
                                   'edificio' => [
                                           'nombre' => 'Edificio ejemplo 1'
                                   ]
                           ];
           }
   
   }

4. Seguido vincularemos la clase rest_aulas_uni a nuestro nuevo recurso recurso_aulas_uni:

   <?php
   
   //personalizacion/php/rest/v1/aulas_uni/recurso_aulas_uni.php
   
   namespace PERS\Guarani\php\rest\v1\aulas_uni;
   
   use SIUToba\rest\rest;
   use SIUToba\rest\lib\rest_validador;
   use SIUToba\rest\lib\modelable;
   use PERS\Guarani\php\rest\v1\modelos\rest_aulas_uni;
   
   class recurso_aulas_uni implements modelable{
   
       /**
        * @var rest_aulas_uni
        */
       protected $modelo;
   
       function __construct()
       {
           $this->modelo = \guarani::rest(rest_aulas_uni::class);
       }
   }

5. Luego a modo de ejemplo crearemos la estructura que tendrá nuestro recurso el cual llamaremos Aula_uni y tendrá los atributos nombre, fecha_creacion, estado y edificio (modelo Edificio_uni):

   <?php
   
   //personalizacion/php/rest/v1/aulas_uni/recurso_aulas_uni.php
   
   namespace PERS\Guarani\php\rest\v1\aulas_uni;
   
   use SIUToba\rest\rest;
   use SIUToba\rest\lib\rest_validador;
   use SIUToba\rest\lib\modelable;
   use PERS\Guarani\php\rest\v1\modelos\rest_aulas_uni;
   
   class recurso_aulas_uni implements modelable{
      
       ............
   
       public static function _get_modelos(){
   
           $edificio_uni = array(
   
               'nombre' => array(
                   'type'          => 'string'
               )
   
           );
   
           $aula_uni = array(
   
               'nombre' => array(
                   'type'          => 'string'
               ),
   
               'fecha_creacion'     => array(
                   'type'          => 'string',
                   '_validar'      => array(rest_validador::TIPO_DATE)
               ),
   
               'estado'     => array(
                   'type'          => 'string',
                   'enum'          => array("A", "B"),
                   '_validar'      => array(rest_validador::TIPO_ENUM => array("A", "B"))
               ),
   
               'edificio'                  => array('$ref' => '#/definitions/Edificio_uni')
           );
   
           return array(
               'Aula_uni' => $aula_uni,
               'Edificio_uni' => $edificio_uni
           );
       }
   }

6. Luego a modo de ejemplo crearemos tres servicios, uno para la creación de un aula (POST /aulas-uni), otro para obtener un listado de aulas (GET /aulas-uni) y un tercero para obtener un aula en particular dado el ID de aula (GET /aulas-uni/{id_aula}):

   <?php
   
   //personalizacion/php/rest/v1/aulas_uni/recurso_aulas_uni.php
   
   namespace PERS\Guarani\php\rest\v1\aulas_uni;
   
   use SIUToba\rest\rest;
   use SIUToba\rest\lib\rest_validador;
   use SIUToba\rest\lib\modelable;
   
   class recurso_aulas_uni implements modelable{
      
       ............
   
       /**
        * POST /aulas-uni
        *
        * Crea una nueva aula.
        *
        * @param_body $aula Aula_uni [required] Campos de un aula.
        *
        * @summary Crea una nueva aula
        *
        * @responses  201 Exito - El aula se creo exitosamente
        * @responses  400 Errores de validación
        * @responses  500 Falló la creación del aula
        **/
       function post_list()
       {
           $datos = rest::request()->get_body_json();
           $this->modelo->post($datos);
           rest::response()->post(['resultado' => 'ok']);
       }
   
       /**
        * GET /aulas-uni
        *
        * @param_query $nombre string Filtro por nombre
        * @param_query $estado string Filtro por estado
        * @param_query $order string (defecto: +nombre,+estado) +/-[nombre,estado] Ordena por nombre o estado
        * @param_query $limit integer (defecto: 20) Limitar a esta cantidad de registros
        * @param_query $page integer Página
        *
        * @notes
        * Devuelve una lista de aulas.<br>
        * Los Filtros se definen como <b>condicion;valor</b>, donde <b>condicion</b> puede ser: <br/>
        * entre, es_mayor_que, desde, es_mayor_igual_que, es_menor_que, es_menor_igual_que, hasta, es_igual_a, es_distinto_de, contiene, no_contiene, comienza_con, termina_con
        *
        * @summary Aulas
        * @responses 200 array {"$ref":"Aula_uni"}
        */
       function get_list()
       {
           $datos = $this->modelo->get_list();
           rest::response()->get_list($datos);
       }
   
       /**
        * GET /aulas-uni/id_aula
        *
        * @notes
        * Retorna los datos del aula.<br>
        *
        * @summary Datos del aula {id_aula}
        * @responses 200 {"$ref":"Aula_uni"}
        * @responses 404 El aula {id_aula} no existe
        */
       function get($id_aula)
       {
           $datos = $this->modelo->get($id_aula);
           rest::response()->get($datos);
       }
   
   }

7. Finalmente debemos dar permisos a dichos servicios en el archivo <path proyecto Guaraní>/instalacion/i__desarrollo/p__guarani/rest/recursos_usuarios.php, por ejemplo:

   //aulas-uni
           'aulas-uni' => [
                   'GET' => ['usuarios' => array_merge($usuarios_admin)],
                   'POST' => ['usuarios' => array_merge($usuarios_admin)],
           ],
           'aulas-uni/id' => [
                   'GET' => ['usuarios' => array_merge($usuarios_admin)]
           ],

Al ingresar a <URL proyecto Guaraní>/rest/v1/ podremos observar el recurso aulas-uni con sus tres nuevos servicios:

Personalizar un servicio REST existente

Si lo que se desea es personalizar un servicio REST existente hacer lo siguiente:

Supongamos que queremos personalizar el recurso docentes, para personalizarlo seguiremos los siguientes pasos:

1. Crear el archivo <path proyecto Guaraní>/personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php, donde uni sera en nombre de la universidad en cuestión (esto es para evitar sobrescribir los servicios provistos por el SIU).
2. Dentro de dicho archivo crear la clase recurso_docentes_uni la cual debe heredar de la clase provista por el SIU (en este caso recurso_docentes):

   <?php
   
   //personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php
   
   use SIUToba\rest\rest;
   use SIUToba\rest\lib\rest_validador;
   use SIU\Guarani\php\rest\v1\docentes\recurso_docentes;
   
   class recurso_docentes_uni extends recurso_docentes {
       ............
   }

A continuación se presentan distintos ejemplos de personalización:

Personalizar los modelos del recurso

Para personalizar los modelos del recurso procedemos a sobrescribir el método _get_modelos para agregar nuevos modelos personalizados, en este caso crearemos el modelo Docente_uni el cual lo copiamos de Docente y le agregamos la propiedad dni:

<?php

//personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php

use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v1\docentes\recurso_docentes;

class recurso_docentes_uni extends recurso_docentes {
   
    ............

    public static function _get_modelos()
    {
        //Obtengo los modelos de la clase padre (recurso_docentes)
        $modelos = parent::_get_modelos();

        //Creo el modelo 'Docente_uni' copiandolo de 'Docente'.
        $modelos['Docente_uni'] = $modelos['Docente'];

        //Le agrego la propiedad 'dni'.
        $modelos['Docente_uni']['dni'] = array('type' => 'string');

        return $modelos;
    }
}

Personalizar un servicio del recurso

En este ejemplo personalizaremos el servicio GET /docentes, el servicio personalizado sera GET /docentes-uni cuyo modelo de datos a retornar sera Docente_uni, también se le modifico la descripción del servicio agregando la frase "[Personalizado]":

<?php

//personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php

namespace PERS\Guarani\php\rest\v1\docentes_uni;

use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v1\docentes\recurso_docentes;

class recurso_docentes_uni extends recurso_docentes {
   
    ............

    /**
     * GET /docentes-uni
     *
     * @param_query $apellido_nombre Filtro Filtro de apellido y nombres del docente
     * @param_query $order string (defecto: +apellido,+nombre) +/-[apellido,nombre,legajo] Ordena por apellido, nombre y/o legajo
     * @param_query $limit integer (defecto: 20) Limitar a esta cantidad de registros
     * @param_query $page integer Página
     *
     * @notes
     * [Personalizado] Devuelve una lista de docentes activos.<br>
     * Los Filtros se definen como <b>condicion;valor</b>, donde <b>condicion</b> puede ser: <br/>
     * entre, es_mayor_que, desde, es_mayor_igual_que, es_menor_que, es_menor_igual_que, hasta, es_igual_a, es_distinto_de, contiene, no_contiene, comienza_con, termina_con
     *
     * @summary Docentes activos
     * @responses 200 array {"$ref":"Docente_uni"}
     */
    function get_list()
    {
        //Se invoca el servicio padre
        parent::get_list();
        //se puede agregar mas código personalizado
    }
}

Finalmente debemos dar permisos a dicho servicio en el archivo <path proyecto Guaraní>/instalacion/i__desarrollo/p__guarani/rest/recursos_usuarios.php, por ejemplo:

//docentes-uni
        'docentes-uni' => [
                'GET' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)]
        ],

Así quedaría el servicio personalizado:

Agregar servicios al recurso

En este ejemplo personalizaremos el recurso docentes-uni agregando dos servicios nuevos PUT /docentes-uni/{id_docente} y DELETE /docentes-uni/{id_docente}:

<?php

//personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php

namespace PERS\Guarani\php\rest\v1\docentes_uni;

use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v1\docentes\recurso_docentes;

class recurso_docentes_uni extends recurso_docentes {
   
    ............

    /**
     * PUT /docentes-uni/id_docente
     * Modifica datos de un docente
     *
     * @param_body $docente Docente_uni Los campos del docente.
     * @notes Los cambios se realizarán sobre el docente {id_docente}
     * @summary Creación o modificación del docente {id_docente}
     * @responses 201 El docente se creó con éxito
     * @responses 204 El docente se modificó con éxito
     **/
    function put($id_docente)
    {
        $datos_docente = rest::request()->get_body_json();
        $res = $this->modelo->put($id_docente, $datos_docente);

        if(is_numeric($res)){ //se creo recien
            rest::response()->post(array('docente' => $id_docente));
        }else {
            rest::response()->set_data('');
            rest::response()->set_status(204); //modificado
        }
    }

    /**
     * DELETE /docentes-uni/id
     *
     * @notes Da de baja físicamente a un docente, junto a sus datos asociados
     *
     * @summary Baja del docente {id_docente}
     * @responses 204 El docente ha sido eliminado
     * @responses 404 El docente {id_docente} no existe.
     */
    function delete($id_docente)
    {
        $this->modelo->delete($id_docente);
        rest::response()->delete();
    }
}

NOTA: Los métodos $this->modelo->put($id_docente, $datos_docente) y $this->modelo->delete($id_docente) se deben agregar en la clase rest_docentes (archivo <path proyecto Guaraní>/personalizacion/php/rest/v1/modelos/rest_docentes.php).

Finalmente debemos dar permisos a dichos servicios en el archivo <path proyecto Guaraní>/instalacion/i__desarrollo/p__guarani/rest/recursos_usuarios.php, por ejemplo:

//docentes-uni
        'docentes-uni/id' => [
                'GET' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)],
                'PUT' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)],
                'DELETE' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)]
        ],

Así se vería el ejemplo finalizado:

Dar de baja un servicio

En este ejemplo personalizaremos el recurso docentes-uni dando de baja el servicio GET /docentes-uni/{id_docente}/comisiones, los servicios REST heredados no pueden ser eliminados por lo tanto lo que haremos es deshabilitar dicho servicio haciendo que arroje una excepción:

<?php

//personalizacion/php/rest/v1/docentes_uni/recurso_docentes_uni.php

namespace PERS\Guarani\php\rest\v1\docentes_uni;

use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v1\docentes\recurso_docentes;

class recurso_docentes_uni extends recurso_docentes {
   
    ............

    /**
     * GET /docentes-uni/id_docente/comisiones
     *
     * @notes
     * Servicio no disponible
     *
     * @summary Servicio no disponible
     * @responses 500 Servicio no disponible
     */
    function get_comisiones_list($id_docente)
    {
        throw new \Exception("Servicio no disponible");
    }
}

Finalmente debemos dar permisos a dicho servicio en el archivo <path proyecto Guaraní>/instalacion/i__desarrollo/p__guarani/rest/recursos_usuarios.php, por ejemplo:

//docentes-uni
        'docentes-uni/id/comisiones' => [
                'GET' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)]
        ],

Así quedaría dado de baja el servicio: