SIU-Guarani/Version3.22.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:
- Crear el archivo <path proyecto Guaraní>/personalizacion/php/rest/v2/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).
- Dentro de dicho archivo crear la clase recurso_aulas_uni la cual debe implementar la interface modelable:
- <?php
//personalizacion/php/rest/v2/aulas_uni/recurso_aulas_uni.php
namespace PERS\Guarani\php\rest\v2\aulas_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIUToba\rest\lib\modelable;
class recurso_aulas_uni implements modelable{
............
}
- 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/v2/modelos/rest_aulas_uni.php:
- <?php
//personalizacion/php/rest/v2/modelos/rest_aulas_uni.php
namespace PERS\Guarani\php\rest\v2\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'
]
];
}
}
- Seguido vincularemos la clase rest_aulas_uni a nuestro nuevo recurso recurso_aulas_uni:
- <?php
//personalizacion/php/rest/v2/aulas_uni/recurso_aulas_uni.php
namespace PERS\Guarani\php\rest\v2\aulas_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIUToba\rest\lib\modelable;
use PERS\Guarani\php\rest\v2\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);
}
}
- 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/v2/aulas_uni/recurso_aulas_uni.php
namespace PERS\Guarani\php\rest\v2\aulas_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIUToba\rest\lib\modelable;
use PERS\Guarani\php\rest\v2\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
);
}
}
- 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/v2/aulas_uni/recurso_aulas_uni.php
namespace PERS\Guarani\php\rest\v2\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);
}
}
- 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/v2/ 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:
- Crear el archivo <path proyecto Guaraní>/personalizacion/php/rest/v2/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).
- 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/v2/docentes_uni/recurso_docentes_uni.php
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v2\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:
//personalizacion/php/rest/v2/docentes_uni/recurso_docentes_uni.php
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v2\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]":
//personalizacion/php/rest/v2/docentes_uni/recurso_docentes_uni.php
namespace PERS\Guarani\php\rest\v2\docentes_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v2\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' => [
'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}:
//personalizacion/php/rest/v2/docentes_uni/recurso_docentes_uni.php
namespace PERS\Guarani\php\rest\v2\docentes_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v2\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/v2/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/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:
//personalizacion/php/rest/v2/docentes_uni/recurso_docentes_uni.php
namespace PERS\Guarani\php\rest\v2\docentes_uni;
use SIUToba\rest\rest;
use SIUToba\rest\lib\rest_validador;
use SIU\Guarani\php\rest\v2\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/id/comisiones' => [
'GET' => ['usuarios' => array_merge($usuarios_admin, $usuarios_verificador)]
],
Así quedaría dado de baja el servicio: