[LINEAMIENTOS Y DIRECTRICES SERVICIOS WEB]

Empresa: Organización Sanitas Internacional

Presentar los lineamientos y directrices generales

Objetivo del documento:
para la construcción de servicios web

Control de versiones:

Versión Fecha Revisado por Descripción del cambio

1 05/08/2014 Fabián Contreras Primera versión.

1.1 21/08/2014 Fabián Contreras Se complementaron definiciones

con base en la revisión realizada.

1.2 29/09/2014 Fabián Contreras Ajustes a lineamientos generales,

donde se indica que las
excepciones se deben manejar en
un documento adicional en cada
proyecto.

1.3 08/05/15 William Cano Inclusión de consideraciones de

implementación para el manejo
de tags opcionales y manejo de
envío sin valor.

1.4 07/10/15 Paul Escobar Se agregan consideraciones de

implementación para
compatibilidad hacia atrás.
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

Índice de contenido

1. Lineamientos Generales...................................................................................4
1.1. Lineamientos....................................................................................................4
2. Manejo de Logs................................................................................................6
2.1. Lineamientos....................................................................................................6
3. Manejo de Excepciones.....................................................................................9
3.1. Lineamientos....................................................................................................9
4. Manejo de Mensajes y Auditoría......................................................................11
4.1. Lineamientos..................................................................................................11
5. Consideraciones de Implementación...............................................................12
6. Requerimientos de Calidad.............................................................................14

OFICINA DE ARQUITECTURA PÁGINA 2 DE

15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

1. Lineamientos Generales

Este capítulo pretende ilustrar y proveer lineamientos a nivel general que deben ser
tenidos en cuenta al momento de la construcción y puesta en producción de los servicios.

1.1. LINEAMIENTOS
 Toda excepción a algún lineamiento deberá tener su debida sustentación y
argumentación de negocio (funcional/contractual) y/o técnica. Cada proyecto donde se
materialice la excepción deberá generar un documento donde se tenga la debida
sustentación.

 Se deben realizar pruebas unitarias sobre todas las capacidades de los servicios.
Cabe recalcar que las pruebas unitarias que se hagan deben ser repetibles, es decir, no
deben depender de datos previos cargados de manera externa a las pruebas, o que la
misma prueba altere datos que hagan que al ejecutarla, por segunda vez falle. Se debe
entregar evidencia e informe de la ejecución de las pruebas en cada entrega de versión
del servicio.

 No dejar parámetros quemados en el código, apoyarse siempre en archivos de

configuración o propiedades.

 Preferir siempre el uso de estándares de la industria a desarrollos personalizados. Por

ejemplo para los temas de seguridad, encripción usar algoritmos de la industria.

 Para desarrollos en plataformas cerradas (.Net, IOS, etc) usar las herramientas
propias de la plataforma, abstenerse de usar frameworks o herramientas de terceros que
pongan en riesgo la compatibilidad a futuro de los desarrollos con la plataforma.

 Aplicar en gran medida los siguientes principios de diseño de servicios:1

 Estandarización del contrato de los servicios.
 Bajo acoplamiento.
 Reusabilidad.
 Autonomía.
 Sin estado.
 Descubribilidad.
 Abstracción.

1
Libro: SOA Principles of Service Design. Author: Thomas Erl. 2008. Editorial: PRENTICE HALL. ISBN: ISBN
0-13-234482-3
OFICINA DE ARQUITECTURA PÁGINA 3 DE
15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

 Apto de Composición.

 Todo servicio debe tener asociado un service profile (ficha técnica), el cual debe irse
actualizando en las diferentes etapas del ciclo de desarrollo, incluido la etapa de soporte y
mantenimiento.

 Las definiciones que se realicen en el service profile de cada servicio deberán detallar
los lineamientos en este documento presentados. Adicionalmente estas definiciones
primaran sobre las generales.

 Los clientes de los servicios no deben acceder directamente a las capacidades del
servicio, sino que lo debe hacer a través de un proxy el cual se debe implementar en la
capa de interoperabilidad2. Adicionalmente el consumo a través del proxy debe hacerse
por el protocolo HTTPS.

 Todo servicio debe poderse balancear a través de un balanceador de carga por

software o hardware.

 Los parámetros no funcionales, de control, de auditoría y cualquier otro que se

requiera, deben ser manejados en el Encabezado (Header) del mensaje no el cuerpo
(Body) del mensaje.

 Se deben hacer pruebas de carga y estrés sobre todas las capacidades del servicio,
generando un informe y análisis con el fin de refinar el sizing de la infraestructura
requerida.

2
Para conocer con más detalle el objetivo y uso de la capa de interoperabilidad por favor remitirse al
documento ARQ - Arquitectura de referencia Capa Interoperabilidad.
OFICINA DE ARQUITECTURA PÁGINA 4 DE
15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

2. Manejo de Logs

Este capítulo provee consideraciones, para el correcto manejo de Logs, apoyado por las
mejores prácticas de la industria que contribuyan a mejorar la calidad de los productos de
software, facilitando con ello el mantenimiento de los servicios y las labores del área de
desarrollo y del centro de cómputo en la identificación y diagnóstico de incidentes.

2.1. LINEAMIENTOS
 No se debe mostrar por consola los errores, si no, usar un sistema de log.

 Todo servicio debe contar con un único y propio registro de eventos (log) para
facilitar el diagnóstico y resolución de fallos.

 El log debe tener características configurables como su activación o desactivación y el

destino de los mensajes.

 Los mensajes del registro deben proveer información clara y suficiente sobre la
actividad del servicio, con el propósito de diagnosticar claramente el problema
presentado. Se deben evitar mensajes como “Ha ocurrido un error interno.” ya que no
proveen información sobre el tipo de error y la causa del mismo.

 La configuración del log debe ser lo menos intrusiva posible en el sistema,

limitándose a la configuración del servicio, sin que requiera modificar su entorno. Por
ejemplo, la configuración del log del servicio no debería depender de la configuración del
servidor de aplicaciones.

 El log debe permitir el manejo de diferentes niveles de registro, por ejemplo INFO,
DEBUG, ERROR, FATAL, y se debe hacer un correcto uso de las mismas.
 DEBUG, para información de muy bajo nivel solo útil para el debug de la
aplicación, tanto en el desarrollo como en el análisis de incidencias.
 Llamadas a funciones y procedimientos y otros componentes, con parámetros
y respuestas.
 Flujos de ejecución.
 Desarrollo de algoritmos y procedimientos que permitan identificar y seguir su
ejecución en desarrollo.
 INFO, información de más alto nivel que permita hacer un seguimiento de la
ejecución normal
 Paradas y arranques de servicios y sistemas.

OFICINA DE ARQUITECTURA PÁGINA 5 DE

15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

 Parámetros críticos o relevantes de configuración.

 Comienzo y fin de transacciones y operaciones completas.
 Cambios de estado de operaciones.
 WARN, información de situaciones, que aún sin ser de error, si son anómalas o no
previstas, aunque el aplicativo tiene alternativas para solventarlas.
 Parámetros no definidos, y cuyo valor se toma por defecto.
 Situaciones anómalas, pero que son resueltas por el aplicativo, dejando la
operación en un estado correcto.
 Funcionalidades no primordiales o imprescindibles, que no pueden resolverse,
pero que dejan la operación en un estado correcto.
 ERROR, información de situaciones que son de error y que impiden la ejecución
correcta de una operación o transacción, pero sin afectar a otras operaciones o
transacciones (error aislado o contenido).
 No se pudo realizar una operación o transacción, pero no afecta a otras.
 Peticiones o consultas erróneas (almacenando los parámetros de entrada).
 Funcionalidades generales del aplicativo, que aún afectando al funcionamiento
general del aplicativo, no se consideran primordiales o imprescindibles.
 FATAL, información de situaciones de error que afectan al funcionamiento general
del aplicativo (errores no aislados o contenidos en alcance).
 Parámetros no definidos o configuraciones erróneas.
 Falta de conexión o comunicación con otros componentes.
 Errores de ejecución que pueden afectar a operaciones o transacciones
independientes, o que afectan al funcionamiento general de la aplicación.

 En lo posible, la implementación del log debe estar basada en librerías y frameworks

especializados en el manejo de Logs propios de la tecnología a utilizar.

 La estructura de registro de la información debe ser configurable con el fin de poder

posteriormente visualizarla con cualquier visor estándar de Log, esto con el fin de buscar
y agrupar información rápidamente.

 Registrar los eventos de manera atómica, que toda la información referente a un

evento se almacene en un registro o línea.

 Hacer uso de mecanismos de información de contexto para entornos de múltiples

hebras o ámbitos de transacciones distribuidas.

 Implementar el método toString() de todas las clases de negocio o POJOs para

facilitar su traceado. Dependiendo de la plataforma utilizada se permite el uso de
mecanismos alternativos que generen un mayor nivel de trazabilidad.

 Hay que tener en cuenta las diferencias y zonas horarias a la hora de trabajar con
logs de varias máquinas o componentes.

 El logging no debe tener efectos laterales, no puede modificar el estado de ningún

parámetro, variable o procedimiento. Solo muestra información. Debe ser ligero, el propio
logging no puede requerir de procesamientos largos o costosos.
OFICINA DE ARQUITECTURA PÁGINA 6 DE
15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

OFICINA DE ARQUITECTURA PÁGINA 7 DE

15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

3. Manejo de Excepciones

Este capítulo provee consideraciones, para el correcto manejo de las excepciones,

apoyado por las mejores prácticas de la industria que contribuyan a mejorar la calidad de
los productos de software, facilitando con ello el mantenimiento de los servicios y las
labores del área de desarrollo y del centro de cómputo en la identificación y diagnóstico
de incidentes, así como la construcción de servicios más robustos.

3.1. LINEAMIENTOS
 Usar un sólo try y varios catch en la implementación de los métodos, y en los catch
capturar y trazar todas las excepciones.

 Evitar el uso de jerarquías, se debe usar muy pocas clases para describir las
excepciones, prefiriendo el uso de código y descripción dentro de la clase para identificar
cada tipo de error. El uso de los mensajes y códigos de error, se deben hacer externos al
código fuente de la aplicación, por ejemplo usando archivos de propiedades, de tal forma
que se pueda hacer uso de la internacionalización en los servicios.

 Excepciones no chequeadas, se deben usar en la mayoría de los casos para describir

un error ante el cual el servicio no se puede recuperar. Esto evita tener que hacer manejo
de excepciones en cada capa donde realmente no se puede hacer nada para recuperar el
servicio del error presentado. La idea es tener solamente una excepción chequeada
dentro del servicio evitando el uso de jerarquía de excepciones.

 Excepciones chequeadas, se deben usar en casos en que el servicio se pueda

recuperar ante el error, que va a ser en muy pocas ocasiones, generalmente esto ocurre
ante casos excepcionales (eventos relativamente raros) en ciertas condiciones de negocio
(ej: saldo insuficiente para realizar la operación: ZeroBalanceException o una excepción
genérica con código: WarningException, code=zeroBalance). Como se ve en el ejemplo,
con las excepciones chequeadas es posible hacer uso de una jerarquía o manejo de
código-mensaje, en estos casos la política no es tan restrictiva como en el caso de las
excepciones no chequeadas.

 Log de las excepciones, en general cada vez que se vaya a lanzar una excepción
debe logearse como ERROR antes de lanzarla, para que quede evidencia de lo que ocurrió
en donde se detecta la situación anormal y no en el que la maneja. En los casos en los
que la necesidad de lanzar la excepción surja por haber atrapado otra excepción de nivel

OFICINA DE ARQUITECTURA PÁGINA 8 DE

15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

bajo (producto de llamar una API de j2se por ejemplo) debe registrarse en el log la causa
también.

OFICINA DE ARQUITECTURA PÁGINA 9 DE

15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

4. Manejo de Mensajes y Auditoría

Este capítulo provee consideraciones, para el manejo de mensajes y Auditoria en la

construcción de los servicios.

4.1. LINEAMIENTOS
 Para cada servicio se debe definir si debe manejar mensajes específicos dependiendo
de la lógica de negocio manejada, tanto para las excepciones, mensajes de error o de
éxito de la ejecución de las capacidades.

 Todos los mensajes que se requieran manejar en el servicio debe ser configurables,
no deben estar quemados en código.

 Se debe propender por la internacionalización del servicio, es decir que los mensajes
se puedan manejar en diferentes idiomas, haciendo uso de archivos de propiedades con
los valores de los mensajes que se quieran manejar.

 La auditoría3 se debe definir por cada servicio, dependiendo de la necesidad puntual

de negocio de lo que se requiera auditar. Para el caso de datos se debe definir una
auditoría a nivel de base de datos, en el caso de acciones se debe definir una auditoría a
nivel de capacidades.

3
Revisar también documento de seguridad informática para las aplicaciones web OSI-CO-Estándar de
Seguridad para Aplicaciones Web
OFICINA DE ARQUITECTURA PÁGINA 10
DE 15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

5. Consideraciones de Implementación

 Tener en cuenta que para la implementación de las capacidades del servicio 4 se

deben utilizar componentes transaccionales (EJB's en el caso de Java).

 Las composiciones que requieran transaccionalidad de servicios, deben manejarse

implementando un estándar de la industria que permita garantizar la transaccionalidad a
través de la orquestación de las capacidades de los servicios, ó a través de sus
componentes transaccionales que soportan la implementación de la capacidades (en el
caso de java los EJB's por ejemplo) y que deben estar preparados para participar en una
transacción distribuida (two fase commit).

 Evitar sobre cargar la lógica de negocio de los servicios con requerimientos no

funcionales de validaciones, autenticaciones o autorizaciones. Utilizar los mecanismos
estándar que provea la industria y la plataforma asociada a la construcción de los
servicios.

 Los tipos de datos a utilizar para representar las estructuras de datos de las entradas
y salidas de las capacidades son:
 Double para atributos que requieren realizar cálculos matemáticos, la precisión
será definida por el negocio.
 String para atributos que no requieren realizar operaciones matemáticas.
 Los campos de fecha se deben manejar como dateTime con formato estándar dado
por la especificación XSD.
 Para el manejo de archivos se debe hacer en base 64.
 Para atributos de verdadero o falso se debe utilizar boolean.

 Las restricciones, validaciones, formatos deben definirse por cada atributo.

 Evitar que el servicio realice cálculos derivados de la los datos que están saliendo,
Por ejemplo calcular la edad a partir de la fecha de nacimiento.

 Los valores de dominio para los atributos que se requieran deben ser configurables
(manejo paramétrico).

 Los aspectos de seguridad asociados al servicio deben ser manejados en le bus

(canal seguro y encripción) siempre y cuando se manejen estándares de la industria.

4
Para mayor información de este tema refierase a la sección 3.2.4 Vista de Implementación del documento
ARQ - Arquitectura de referencia Capa Interoperabilidad.
OFICINA DE ARQUITECTURA PÁGINA 11
DE 15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

 La documentación técnica mínima requerida para un servicio, es el Service Profile y

el documento de análisis técnico.

 Las invocaciones a capacidades de lectura siempre serán de manera síncrona. Por

otro lado en lo posible realizar invocaciones asíncronas a las capacidades de escritura.
Esta asincronía debe estar a cargo de la aplicación cliente y apoyada en la capa de
interoperabilidad.

 Las homologaciones de los atributos manejados con valores de dominio (tipo de

documento, compañías, códigos, etc), deben ser realizadas en las aplicaciones clientes de
los servicios contra el modelo canónico.

 Los servicios cuyas capacidades tengan en sus mensajes de entrada campos

opcionales deben soportar que NO llegue el tag como parte del mensaje o que llegue pero
que éste sea vacío (<tag></tag> o </tag>). Es decir, la ejecución de la capacidad no
se debe ver afectada porque llegue o no el tag o por si viene nulo. Sin embargo cuando el
campo no pueda ser nulo y el cliente envíe el tag vacío o cerrado, el servicio deberá
validar el valor del campo y retornar una excepción cuando así se especifique.

 En las capacidades cuyos mensajes de salida tengan campos opcionales y éstos sean
elementos XML, si el valor es nulo el elemento no se enviará. Dado lo anterior se debe
tener en cuenta que si sobre ese elemento se deben hacer operaciones, validaciones o
conversiones en la capa de interoperabilidad el elemento debe ser obligatorio y traer
algún valor.

 Compatibilidad hacia atrás de los esquemas. Cuando aparece un campo nuevo de

SALIDA (así sea opcional), el cliente debe ser regenerado, si el campo no se necesita no
debe implicar modificación del código fuente, solo del .jar que contiene el cliente.

 Compatibilidad hacia atrás de los esquemas. Cuando aparece un campo nuevo de

ENTRADA opcional, el cliente no necesita ser regenerado, así que no se incurre en
ninguna cambio.

OFICINA DE ARQUITECTURA PÁGINA 12

DE 15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

6. Requerimientos de Calidad

 Disponibilidad: Un SW debe estar listo para su uso inmediato o en un momento

determinado. La disponibilidad también está asociada con la disponibilidad del tiempo de
reparación (TTR) cuando un servicio ha fallado y que indudablemente se espera que sea
durante un tiempo corto.

 Accesibilidad: Es el grado de capacidad para aceptar una solicitud de servicio. Se

puede expresar como una medida de probabilidad, que indica el porcentaje de éxito o de
posibilidad de una creación de instancias de servicios de éxito en un punto en el tiempo.
Es difícil saber las situaciones en que un SW está disponible, pero no es accesible. Una
solución para una buena accesibilidad es construir sistemas altamente escalables, de alta
disponibilidad, a pesar de lo variable de las solicitudes.

 Integridad: El SW debe mantener la exactitud de los datos en la interacción con

respecto a la fuente, y la correcta ejecución de las transacciones. Cada transacción debe
tratarse como una secuencia de actividades, pero en una sola unidad de trabajo, de tal
manera que todas las actividades deben ser completadas, o de lo contrario todos los
cambios realizados serán deshechos.

 Rendimiento: Se mide en términos de desempeño y latencia. Un mayor rendimiento

y los valores de latencia más bajos representan un buen desempeño. El rendimiento se
puede representar como el número de solicitudes a SW, asistidas en un periodo de tiempo
determinado. La latencia es el tiempo que tomó prestar el servicio, desde el envío de una
solicitud hasta la llegada de la respuesta.

 Fiabilidad: Tiene que ver con mantener en funcionamiento el servicio. El número de

fallos por mes o año puede ayudar a llevar un control y una medida de la fiabilidad de un
servicio Web; también puede referirse a la seguridad en cuanto a la entrega de mensajes
enviados y recibidos por los solicitantes de servicios y por los proveedores de servicios.

 Regulación: Es la conformidad con las normas, de acuerdo al nivel de servicio

establecido. Los SW se basan en una variedad de estándares como SOAP (Simple Object
Access Protocol), UDDI (Universal Description, Discovery and Integration) y WSDL (Web
Services Description Language). Es necesario que los proveedores de servicio cumplan
estrictamente las versiones correctas de los estándares (por ejemplo, la versión SOAP
1.2), para que los solicitantes invoquen adecuadamente los SW.

 Seguridad: Es la confidencialidad y la autenticación correcta de las partes

involucradas, los mensajes de cifrado y el control de acceso proporcionado por los
OFICINA DE ARQUITECTURA PÁGINA 13
DE 15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

prestadores del SW. El proveedor de servicios puede tener distintos enfoques y niveles de
prestación de seguridad en función del solicitante del servicio.

A continuación se presenta una tabla con valores y atributos de referencia, para ser
tenidos en cuenta en la definición de los mismos en el Service Profile. Estos valores han
sido tomados como referentes de la industria, sin embargo se aclara que estos deberan
ser definidos en cada Service Profile.

Atributo Valor Estandar Razón Ámbito

Valores de latencia
Tiempo de más bajos
250ms – 500ms WS
respuesta representan un buen
desempeño

Mayor o igual a 99%

(equivalente a 7,2h El WS siempre debe
Disponibilidad WS
de interrupción o estar disponible
menos cada mes)

La confidencialidad y
la autenticación
Seguridad WS-Security WS, Capacidad
correcta de las partes
involucradas

SOAP 1.1, SOAP 1.2, Se debe estandarizar

Regulación WSDL (Top Down), para lograr la WS
WS-I interoperabilidad

El WS debe soportar
Concurrencia 1000 usuarios muchos usuarios WS
conectados a la vez

Media mayor que

Flujo/Velocidad 60% del Conectividad y
WS
Media flujo/velocidad velocidad
máxima contratada

Tiempo para
El WS siempre debe
establecimiento 1 min WS
estar disponible
de conectividad

Después de un tiempo
Tiempo de Espera de inactividad el
45 segundos WS
(TimeOut) servicio genera una
excepción.

OFICINA DE ARQUITECTURA PÁGINA 14

DE 15
 VICEPRESIDENCIA DE ÁREA ARQUITECTURA LINEAMIENTOS Y DIRECTRICES SERVICIOS
OPERACIONES Y TECNOLOGÍA

7. Consumo Servicios

En este capítulo se describen los lineamietos relacionados con los servicios ofrecido y/o
consumidos desde las aplicaciones de la organización.

7.1. LINEAMIENTOS GENERALES

 Todos los servicios creados por la organización deben quedar expuestos en la de capa
de interoperabilidad a través de un proxy en el bus de servicios.

 El consumo de servicios (internos o externos) desde las aplicaciones se debe realizar

a través de los proxies expuestos en la capa de interoperabilidad.

 Para la creación de proxies en la capa de interoperabilidad se debe primero crear un

endpoint y posteriormente referenciarlo desde el proxy.

 Los consumidores de los servicios web (aplicaciones, procedimientos, servicios, etc.)

serán los responsables de realizar las homologaciones u operaciones necesarias para
llevar a cabo el consumo de los servicios. Es decir, los servicios no se deben adaptar
a los parámetros de entrada de un consumidor en particular sino que los clientes se
deben adaptar a la información de entrada y salida diseñada para cada servicio.

7.2. CLIENTE ROBUSTO

-------------------------------------------------------------

 Se deben manejar timeouts.

 Se debe enviar mediante cabecera identificación del cliente para efectos de
estadísticas y seguimientos de problemas.

OFICINA DE ARQUITECTURA PÁGINA 15

DE 15