| Tabla de contenidos | ||
|---|---|---|
|
Parámetros de cabecera
Para consumir los diferentes métodos REST que aparecen en la definición de la API debe contar con los permisos necesarios.
...
- Authorization: Token de operación generado en el proceso de login. Debe ir precedido del literal "JWE" (ejemplo, JWE <hash del token de operación>).
- version: Versión del recurso a ejecutar con el formato siguiente: v1.0
- rol: Rol del usuario que está ejecutando el recurso.
- contexto: Contexto sobre el que se está ejecutando el recurso.
- sistema: Sistema en el que se está ejecutando el recurso.
- delegado: Usuario DMSAS del técnico que realiza la consulta o acción. Este parámetro es requerido.
Formatos y valores tabulados
Las interfaces habilitadas reciben parámetros que pueden ser:
...
Estos parámetros podrán ser enviados en el cuerpo de la petición (body) o bien en la url de invocación (query), según se especifique en la definición de la API.
Formato de fechas
El formato de fecha con el que trabaja la API es el formato date-time: 2019-02-04T11:56:24.143Z
Este formato recoge la fecha en horario GMT, por lo que el usuario de la API deberá convertir el formato de fecha de forma acorde para el correcto funcionamiento de las consultas y modificaciones que se realicen sobre las entidades. Es decir, el usuario deberá convertir la fecha actual (GMT+1 o +2 en verano) a horario GMT antes de enviarla como parámetro en una llamada; del mismo modo, en la consulta de información, los valores se mostrarán en horario GMT, por lo que habrá que realizar la conversión de forma inversa.
Formato HATEOAS
Algunas respuestas contendrán un atributo links, que hace referencia a un elemento de la respuesta que puede consultarse de forma más extensa mediante un enlace específico. Este atributo contendrá un array de objetos con los mismos dos valores:
...
| Info |
|---|
Los identificadores no tienen por qué coincidir entre entornos, por lo que recomendamos el uso de los métodos GET de la API previos a una creación o modificación para tener datos reales y válidos. |
Paginación y filtrado de respuestas
Paginación de listados
La API cuenta con una funcionalidad de paginación para los métodos que devuelvan un listado con alta cantidad de elementos.
...
Además de estos parámetros, la consulta de la primera página devuelve el total de registros actuales en el parámetro total de la respuesta, por lo que a partir de ese valor puede calcular las páginas disponibles en función de los registros por página consultados en la llamada.
Ejemplo: Queremos consultar el REST de obtención de un listado de solicitudes de 20 en 20 registros y consultar la página 3.
...
| URL parcial |
|---|
| /cges/tablas/solicitudes?registros=20&pagina=3 |
Filtrado de la respuesta
Si sólo necesita que la respuesta incluya un conjunto limitado de la información devuelta por consumo de datos o claridad en la información, puede hacer uso del parámetro _incluir. Este parámetro permite enviar varias cadenas de texto haciendo referencia a la estructura de la respuesta para obtener los datos filtrados.
Ejemplo: Queremos consultar el REST de obtención de un listado de solicitudes y obtener el número de la solicitud, el recurso afectado y la fecha de apertura.
...
| Respuesta filtrada obtenida |
|---|
{ |
Ordenación de listados
Esta sección contiene información acerca del formato necesario para solicitar la ordenación de listados.
Formatos de atributos
Actualmente, la ordenación de listados sólo está disponible para los siguientes métodos de la API:
...
Para ordenar, es necesario enviar un parámetro de consulta _ordenar con el nombre del campo por el que se pretender ordenar seguido del modificador :asc o :desc para la ordenación ascendente o descendente respectivamente. Si no se envía un modificador, la ordenación es ascendente. Sólo se puede enviar un máximo de tres parámetros de ordenación.
Ejemplo: Ordenar la consulta por el nombre del recurso de forma ascendente, la fecha de apertura de forma descendente y el usuario asignado de forma ascendente.
...
| URL parcial |
|---|
| /cges/tablas/solicitudes?_ordenar=recurso.recurso&_ordenar=fechas.fechaApertura:desc&_ordenar=usuarioAsignado.usuarioAsignado:asc |
Operaciones por lotes
Para consumir los recursos REST de Servicios CGES, en ocasiones será necesario la utilización de operaciones por lotes u operaciones de batch para mantener la integridad de una operación en la que intervienen diferentes recursos para alcanzar un mismo fin. Esta forma de operar asegura la coherencia del proceso y obliga a la persona que consume el servicio a realizar las operaciones en un conjunto y orden determinados.
Para ello, habrá que consumir el servicio a través del siguiente método REST:
Estructura de la petición de batch
Todas las operaciones por lotes deberán realizarse sobre una misma solicitud.
Tendremos que incluir la cabecera (header) para la llamada.
...