Operativa general

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.

Además, el funcionamiento correcto de las llamadas al servicio depende del envío en la cabecera de los siguientes parámetros:

• 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:

• Textos libres, números o booleanos.
• Cadenas o valores establecidos (Ej. Códigos de estado: “OP”, “FIX”, “DEL”)
• Valores en formatos específicos (Ej. Fechas en formato date-time)
• Identificadores de otras entidades, en cuyo caso tendrá que especificarse un valor extraído de otra interfaz (Ej. Parámetro id de /cges/tablas/nodos)

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:

• rel: Tipo de relación que guarda el enlace respecto a la entidad en la que está contenido en atributo links. Cuando se indica el valor self, el enlace hace referencia a la propia entidad.
• href: Enlace parcial a la información extendida. Este enlace habrá que completarlo con la URL del servicio en función del entorno en el que se encuentre.

Formato de identificadores

Por la naturaleza de la aplicación sobre la que se sustenta CGES, los identificadores de las entidades pueden tomar tres formatos diferentes:

• UUID: Los identificadores de tipo UUID representan un valor de 32 caracteres en formato hexadecimal. (Ejemplo: 544DAD9A2D8901F2A523001CC416E56E)
• ID: Los identificadores de tipo ID representan un valor de entero. (Ejemplo: 400012)
• PERSID: Los identificadores de tipo PERSID suelen ir precedidos de un literal y separados por ":". (Ejemplos: rc:400258, pcat:400002)
  
  

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.

El método recibe los siguientes parámetros de consulta:

• pagina: Número de página que se desea consultar. Si no se envía, se consulta por defecto la página 1.
• registros: Número de registros por página a consultar. Si no se envía, se extraen por defecto 50 registros, el valor máximo disponible.

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.

Para consultar el listado de solicitudes tendremos que consumir el siguiente método de la API:

Para conseguir la respuesta filtrada que necesitamos, habría que realizar la llamada con la siguiente URL:

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.

Para consultar el listado de solicitudes tendremos que consumir el siguiente método de la API:

Para conseguir la respuesta filtrada que necesitamos, habría que realizar la llamada con la siguiente URL:

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:

La ordenación se realiza sobre los atributos de la respuesta que comprenden cada uno de los elementos del array JSON.

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.

Para conseguir la respuesta ordenada que necesitamos, habría que realizar la llamada con la siguiente URL:

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.

La estructura del cuerpo de la petición (body) comprende un array con tantos elementos como métodos de REST quieran ejecutarse. En dichos elementos se incluirá toda la información necesaria para ejecutar independientemente un método REST, siendo todos obligatorios:

• El atributo metodo contendrá el tipo de recurso: GET, POST, PUT o DELETE.
• El atributo uri contendrá la URI parcial del método REST a ejecutar, ya construida con todos los parámetros de path necesarios. (Ejemplo: /cges/solicitudes/4664334/actuaciones)
• El atributo headers debe contener los mismos parámetros que para un método normal, pero estructurados con otro formato.
• El atributo body contendrá un objeto con todos los parámetros que deban ir en el cuerpo de la petición REST.
  
  
  

[{
        "metodo": "POST",
        "uri": "/cges/solicitudes/4664331/actuaciones",
        "headers": [{
                "nombre": "version",
                "valor": "v1.0"
            }, {
                "nombre": "delegado",
                "valor": "apellidonombre11A"
            }, {
                "nombre": "rol",
                "valor": "PROVEEDOR"
            }, {
                "nombre": "contexto",
                "valor": "DEFAULT"
            }, {
                "nombre": "sistema",
                "valor": "ESB"
            }, {
                "nombre": "delegado",
                "valor": "apellidonombre11a"
            }
        ],
        "body": {
            "horas": 1.00,
            "factorTiempo": 400001,
            "perfil": 400001,
            "causa": 1,
            "tipoActuacion": 401038,
            "fecha": "2018-02-06T09:17:32.000Z",
            "comentario": "Incurriendo horas...",
            "visibleUsuario": false,
            "tecnicoDmsas": "apellidonombre11A"
        }
    }, {
        "metodo": "PUT",
        "uri": "/cges/solicitudes/4664331/estado",
        "headers": [{
                "nombre": "version",
                "valor": "v2.0"
            }, {
                "nombre": "delegado",
                "valor": "apellidonombre11A"
            }, {
                "nombre": "rol",
                "valor": "PROVEEDOR"
            }, {
                "nombre": "contexto",
                "valor": "DEFAULT"
            }, {
                "nombre": "sistema",
                "valor": "ESB"
            }, {
                "nombre": "delegado",
                "valor": "apellidonombre11a"
            }
        ],
        "body": {
            "estado": "400001",
            "comentario": "Resolviendo solicitud...",
            "tecnicoDmsas": "apellidonombre11a
        }
}]

El método de batch puede devolver dos tipos de estructura de error en función de si el error ocurre en una validación previa a la ejecución del batch (por ejemplo, en la validación de campos) o durante la ejecución del batch (por ejemplo, un error inesperado en una de las operaciones unitarias), en cuyo caso puede devolverse en un estado HTTP incorrecto en cualquier nivel de la respuesta.

{
    "descripcion": "000029",
    "errores": [{
            "campo": "error",
            "mensaje": "Acción no permitida en el estado actual de la solicitud.",
            "codigo": "000029",
            "visible": true
        }
    ]
}

[{
        "status": 200,
        "body": {
            "idActuacion": "1453493",
            "descripcion": "Actuacion generada correctamente.",
            "visible": true
        }
    }, {
        "status": 200,
        "body": {
            "idSolicitud": "6018778",
            "descripcion": "Solicitud modificada correctamente.",
            "visible": true
        }
    }, {
        "status": 409,
        "body": {
            "descripcion": "000054",
            "errores": [{
                    "campo": "error",
                    "mensaje": "El registro que intenta modificar se encuentra bloqueado temporalmente.",
                    "codigo": "000054",
                    "visible": false
                }
            ]
        }
    }, {
        "status": 409,
        "body": {
            "descripcion": "Ha ocurrido un error en una operación de batch bloqueante, no se ejecutará el resto de operaciones.",
            "errores": [{
                    "campo": "ex",
                    "mensaje": "Ha ocurrido un error en una operación de batch bloqueante, no se ejecutará el resto de operaciones.",
                    "codigo": "409",
                    "visible": false
                }
            ]
        }
    }
]