Documentación de APIs REST

Documentación de APIs REST

La documentación se genera en base a los annotations del código y el método _get_modelos() de cada clase. Los modelos se utilizan para definir tipos de datos compuestos (Persona, Docente, Recibo, etc.) y luego pueden referenciarse desde las anotaciones de cada método. Por ejemplo, para indicar que el método get_list() de la clase recurso_personas retorna una lista de Persona, o para indicar el formato del objeto que espera el método post_list() es una Persona.

Anotaciones de los métodos

A continuación se muestra un método anotado de ejemplo y se detallan los tipos de anotaciones y su función:

    /**
     * GET /cursos
     *
     * @param_query $estado string (defecto: A) [A\B] Filtra cursos activos o en baja
     *
     * @param_query $limit integer (defecto: 20) Limitar a esta cantidad de registros
     * @param_query $page integer página
     * @param_query $order string (defecto: +curso) +/-[curso,nombre] Ordena por el/los campos
     *
     * @notes  Los cursos agrupan comisiones y ofrecen consultas convenientes para sistemas externos, como los alumnos que deberían conformar el curso.
     *   Los Filtros se definen como 'condicion;valor' donde 'condicion' 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       Lista de Cursos
     * @responses 200 array {"$ref":"Curso"} Arreglo de cursos
     * @responses 200 Exito
     * @responses 400 Error en los parámetros
     */
	function get_list()

Parámetros

Hay 3 tipos de parámetros en una API.

• Identificador de recursos: es el que aparece en la URL de la API. Por ejemplo GET /personas/{id_persona}. El valor del mismo se obtiene del nombre del parámetro en el propio código php. En el caso mencionado, la declaración sería recurso_personas::get($id_persona) {}.

• Parámetros de la url (query string): son aquellos especificados luego del "?", por ejemplo GET /personas?param1=abc&param2=xyz. Para especificarlos en la documentación se usa la anotación @param_query $[nombre] [tipo] [descripcion]

• Parámetros del cuerpo del mensaje (body): son aquellos enviados con formato json en el cuerpo del mensaje. Generalmente son del tipo de algún modelo (objeto) y se representan con la anotación @param_body $[nombre] [Modelo|tipo] [descripcion]

Otros

• @notes se utiliza para documentar comentarios destinados a los consumidores de la API
• @summary una descripción breve que se muestra en el listado global de lo métodos junto a cada uno.
• @responses se utiliza para indicar los distintos estados y descripciones de la respuesta. Ademas se puede indicar el tipo de la respuesta. Puede ser un tipo simple, o si es un arreglo (el formato de Swagger es: array {"$ref":"[ID_Modelo]"})

Modelos

Para proveer modelos las clases tienen que implementar \rest\lib\modelable (extender de dicha clase es opcional, solo se provee a fines documentativos). La misma tiene solo un metodo _get_modelos() que debe retornar un arreglo de los modelos de la clase. El id de cada uno es la llave del arreglo, y con el mismo se deben referenciar desde las anotaciones.

El modelo se construye con los campos del lado izquierdo, y pueden contener un arreglo con mayor detalle. Se debe indicar de forma explícita todos los tipos de los campos.

Los tipos de datos y campos posibles estan definidos en la documentación de swagger, y la librería solo los convierte a JSON, salvo que estén reservados.

Funcion de mapeo y validación

El modelo puede utilizarse con rest_hidratador para asegurarse que siempre se retorna un objeto que respeta la documentación. Para esto se le entrega la especificación y el recordset de la base de datos que desea validarse. Además se pueden agregar reglas al modelo para mapear y transformar los campos.

 rest_hidratador::hidratar([Modelo], $recorset_bd);

Los campos reservados son

• _mapeo: el valor del campo se toma de la columna _mapeo.
• _compuesto: el valor del campo es un subarreglo que se calcula recursivamente con dicha especificacion.
• _id: la fila que no se debe repetir, se usa al agrupar filas con el mismo id, se agrupan segun las columas _agrupado.
• _agrupado: si la columna tiene este atributo se agrupan los valores de la misma entre filas que compartan la columna _id.

Ejemplos

'Curso' => array(
        'id_curso_externo'=> array('_mapeo' => 'curso', 'type' => 'integer'),
        'nombre' => array('type' => 'string'),
        'estado' => array('type' => 'string', 'enum' => array('A', 'B')),
        'id_plataforma' => array('_mapeo' => 'sistema', 'type' => 'integer'),
        'comisiones' => array('type'=> 'array', 'items'=> array('type'=> 'Comision')),
),

'Comision' => array(
	"comision"	=> array('type' => 'integer'),
	"nombre" 	=> array('type' => 'string'),
	"catedra"    	=> array('_mapeo' => "nombre_catedra", 'type' => 'string'),
	"modalidades" 	=> array('_mapeo' => "nombre_modalidad",
				  "type"   => "array", "items" => array("\$ref" => "string")
	),
	"turno"		=> array('_compuesto' => array('turno'  => array('type' => 'string'),
						       "nombre" => array('_mapeo' => "nombre_turno", 'type' => 'string')
						       )
	),
	'ubicacion'     => array('_compuesto' => array('ubicacion'		=> array('type' => 'string'),
						       'nombre_ubicacion'	=> array('_mapeo' => "nombre", 'type' => 'string')
						       )
	),
	'actividad'         => array('_compuesto' => array('codigo' => array('_mapeo' => "codigo_actividad", 'type' => 'string'),
							   'nombre' => array('_mapeo' => "nombre_actividad", 'type' => 'string')
							   )
	),
	'periodo_lectivo'   => array('_compuesto' => array('periodo_lectivo' => array('type' => 'integer'),
							    'nombre' => array('_mapeo' => "nombre_periodo", 'type' => 'string'),
							  )
	),
),
);

'Agrupacion' => array('comision' => array('_id'),
		      'horarios' => array('_agrupado', 
					  '_compuesto' => array('dia'    => array('_mapeo' => 'horario_dia', 'type' => 'date'),
							        'inicio' => array('_mapeo' => 'horario_inicio', 'type' => 'time'),
							        'fin'    => array('_mapeo' => 'horario_fin', 'type' => 'time')
									      ),
					  )
)

//Esto mapea `[comision1; horario1], [comision1; horario2], [comision1; horario3]` a: `[comision1; [horario1, horario2, horario3]]`