Documento de Desarrollo de Servicios Web SOAP

INTRODUCCIÓN

1.1 Objeto

El objetivo de este documento es establecer la normativa a seguir sobre la definición e implementación de Servicios Web SOAP que se desarrollen en la Consejería de Presidencia, Interior, Diálogo Social y Simplificación Administrativa.

1.2 Alcance

Este procedimiento va dirigido a todo el personal con responsabilidades en la toma de decisiones dentro de cada ámbito de actuación que se defina en el documento. 

• Directores de proyectos, que han de velar por el conocimiento y puesta en práctica de la normativa por parte de los equipos de desarrollo.
• Equipo de desarrollo, que ha de cumplir las normas aquí presentadas.
• Equipo de explotación, que ha de gestionar y administrar los componentes software objeto de este documento.
• Equipo de Interoperabilidad, responsable de la Plataforma y del gobierno de la interoperabilidad. 

El ámbito de aplicación es la Dirección General de Estrategia Digital y Gobierno Abierto de la Consejería de Presidencia, Interior, Diálogo Social y Simplificación Administrativa, siendo una recomendación fuera de este contexto.

1.3 Condiciones de Uso

Las normas recogidas en esta guía son de obligado cumplimiento, dentro del alcance especificado. La Oficina Técnica de Interoperabilidad de la Consejería de Presidencia, Interior, Diálogo Social y Simplificación Administrativa (en adelante OT-I) se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata. 

La OT-I podrá estudiar los casos excepcionales, en el caso de que algún actor considere necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehacientemente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida para proceder a su validación técnica. 

Tras el análisis de la información aportada, la OT-I informará de manera explícita sobre las conclusiones obtenidas para lograr encontrar una solución adaptada en la medida de lo posible a las directrices marcadas.

NORMAS Y BUENAS PRÁCTICAS

A continuación se presenta un resumen de las normas y buenas prácticas de aplicación en el contexto del desarrollo. 

Para más información, consulte los apartados que desarrollan los contenidos.

2.1 Desarrollo de Servicios WEB

2.1.1  Elaborar un Perfil de Integración

Cuando se produce una integración entre dos o más sistemas de información entre los cuales se realizará un intercambio de información a través de varios servicios web se debe crear un perfil de integración para poder recoger todos los aspectos semánticos, sintácticos y técnicos que conlleve la integración. 

Este documento será la base para las futuras evoluciones e incluso resolución de problemáticas que puedan surgir. 

La OT-I pone a disposición de la Dirección General, la plantilla sobre la cuál deberá realizarse el perfil: DGPD_NORM_Plantilla Perfil de Integración. 

2.1.2  Adoptar una estrategia Contract-first

Se debe adoptar una estrategia de desarrollo Contract-first: primero definición del servicio y luego desarrollos. 

2.1.3 Utilizar protocolos de comunicación SSL 

La comunicación entre sistemas de información, cuando uno de ellos pertenece a la Dirección General debe ser a través del protocolo de comunicación SSL/TLS. 

2.1.4  Seguir la política de versionado de servicios

Se deberá versionar el servicio ante cambios que impliquen la adaptación de los consumidores y mantener la versión anterior durante el tiempo acordado. 

2.2 Desarrollo de servicios SOAP

2.2.1 Documentar de forma diferenciada los elementos comunes

Para aquel sistema cuyo especificación disponga de elementos comunes a varios servicios web deberán recogerse de forma única en un documento de elementos comunes. 

La OT-I pone a disposición de la Dirección General, la plantilla sobre la cuál deberá realizarse el documento: DGPD_NORM_Plantilla Elementos Comunes. 

2.2.2 Publicar el WSDL

Los servicios web desarrollados deben hacer público su  WSDL. 

2.2.3 Emplear el patrón de diseño XML Schema

Los esquemas XML utilizados deberán cumplir las especificaciones WS-I Basic Profile.

2.2.4. No utilizar XML incrustado en el propio mensaje

No se permiten parámetros que contengan XML incrustado como texto, todas las etiquetas han de estar definidas como parámetros. 

2.2.5. Evitar el intercambio de documentos en los mensajes

Se recomienda evitar en la medida de lo posible la transmisión de ficheros sobre el body y usar, en su lugar, mecanismos de transmisión como MTOM. 

2.2.6. Aplicar la nomenclatura de los servicios

El nombre del servicio debe ser acorde a la funcionalidad del mismo con estilo CamelCase y solo con caracteres alfanuméricos.

2.2.7. Aplicar la especificación de los servicios seleccionada

Se deben desarrollar los servicios acordes a la especificación elegida. Si el servicio es SOAP 1.1, todos los mensajes intercambiados deben seguir la especificación de SOAP 1.1. 

2.2.8. Equilibrar la granularidad de operaciones por servicios 

Se recomienda buscar un equilibrio entre el número de servicios y operaciones, evitando la definición del WSDL del servicio con una excesiva granularidad de operaciones. 

2.2.9. Emplear la cabecera Conten-Type 

Se debe usar la cabecera Content-Type "application/soap" o "apllication/soap+xml".

CONCEPTOS GENERALES

3.1. Arquitectura Orientada a Servicios (SOA)

La evolución que los Sistemas de Información han experimentado en los últimos años han incrementado las necesidades de compartir información e interoperar entre ellos. Ante este escenario la OT-I ha definido una estrategia de interoperabilidad basada en una SOA como paradigma de arquitectura para sistemas distribuidos que cubra las necesidades funcionales de manera ágil, f iable y flexible, ganando además en seguridad y trazabilidad. 

Para implementar con éxito una SOA se consideran destacables los siguientes principios:

• Bajo acoplamiento: Es uno de los factores críticos para el éxito de la estrategia SOA. El objetivo del bajo acoplamiento es reducir las dependencias entre los sistemas implicados.
• Reutilización: Un servicio debe ser diseñado y construido pensando en su reutilización dentro de la misma aplicación o en la organización para su uso masivo.
• Descubrimiento: Todo servicio debe poder ser descubierto de alguna forma para que pueda ser utilizado, consiguiendo así evitar la creación accidental de servicios que proporcionen las mismas funcionalidades.
• Interoperabilidad: Permite que los consumidores y los servicios desarrollados en tecnologías y plataformas diferentes puedan compartir información y colaborar.
• Gobernabilidad: En un entorno SOA, la gobernanza guía el desarrollo de servicios reutilizables, estableciendo cómo se diseñarán, cómo se desarrollarán los servicios y cómo cambiarán con el tiempo. La Gobernanza establece acuerdos entre los proveedores de servicios y los consumidores de esos servicios, indicando a los consumidores lo que deben esperar y lo que los proveedores están obligados a proporcionar. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 9 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital 

La pieza clave de una Arquitectura SOA son los servicios. Un Servicio Web es una parte del software que puede comunicarse con otra aplicación a través de una red usando un conjunto específico de protocolos estandarizados tales como SOAP, REST, UDDI, WSDL. Entre los principales beneficios que se exponen al hablar de los Servicios Web, generalmente se encuentran aquellos que tienen que ver con granularidad e interoperabilidad, es decir, con la posibilidad de desarrollar componentes de software totalmente independientes que tienen funcionalidad propia, pero que son capaces de exponer tal funcionalidad y compartirla con otros servicios y aplicaciones para lograr crear sistemas más complejos. 

Distintas aplicaciones de software desarrolladas en lenguajes de programación diferentes, y ejecutadas sobre cualquier plataforma, pueden utilizar los Servicios Web para hacer uso de los servicios expuestos en redes de ordenadores como Internet. Las organizaciones OASIS y W3C son los comités responsables de la arquitectura y reglamentación de los Servicios Web. 

Las operaciones que ofrezca un servicio han de ser coherentes con la parte del negocio que representan, no permitiéndose la encapsulación en un solo servicio de toda la funcionalidad aplicable a un determinado modelo de negocio complejo. Esto permite la clara identificación de los servicios de negocio, disponiendo cada servicio de una responsabilidad única. Los Servicios Web que se diseñen implicarán responsabilidades bien repartidas, de tal manera  que sean escalables y reutilizables.

3.2. Perfil de Integración

Cada vez que exista una necesidad de integración, con mas de un servicio, que implique definir la interacción entre los distintos servicios debe crearse un perfil de integración para ello. En este documento se explica la solución de integración diseñada para una necesidad concreta. La plantilla que seguirá este documento es DGPD_NORM_Plantilla Perfil de Integración, en su última versión, y su estructura es:

• Introducción: En este apartado se describe el objeto del documento, que será la explicación sobre la necesidad de integración que se precise. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 10 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital
• Alcance del proceso de interoperabilidad: Descripción de las funcionalidades que debe cubrir el proceso de interoperabilidad, tales como contexto y requisitos.
• Descripción general del proceso de interoperabilidad: En este apartado se especifica los actores y los distinto casos de uso que se darán en la integración junto con el flujo de ejecución de cada uno de ellos.
• Definición dinámica: Para cada uno de los casos de usos expuestos en el punto anterior debe definirse un diagrama de secuencia.
• Definición estática: Se especifican cada uno de los servicios nombrados en el documento. Para cada servicio se informará sobre nombre, operación, proveedor, tipología del servicio y contrato del servicio. 

El Perfil de Integración debe ser el primer documento a leer por los desarrolladores de los servicios. Una vez se tenga el conocimiento funcional global de la integración se aumentará el conocimiento con la información técnica proporcionada en cada uno de los contratos de los servicios, referenciados en el propio documento del perfil.

3.3. Contrato del Servicio Web

Cada Servicio Web desarrollado ha de disponer de un contrato del Servicio asociado. Este contrato seguirá la plantilla DGPD_NORM_Plantilla Contrato Servicio Web, en su última versión, que se estructura de la siguiente forma:

• Servicio: En este apartado se describe los principales aspectos del servicio: nombre, tipología, objetivo, endpoint, versión, seguridad, autenticación, namespace, descripción del servicio web, alertas SLA, tiempos de respuesta y otras observaciones que se consideren necesarias.
• Operaciones: Para cada una de las operaciones del servicio se describe: nombre, objetivo, método HTTP (si procede), encoding, mensaje de entrada y salida, junto con sus respectivos esquemas y parámetros de entrada/salida.
• Tipos de Datos: Descripción de los tipos de datos específicos del servicio que dan soporte a las operaciones del mismo. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 11 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital Especificar que aquellos tipos de datos comunes para más de un servicio dentro del mismo Sistema vendrán informados en un documento aparte, cuya plantilla es DGPD_NORM_Plantilla Elementos Comunes, en su última versión.
• Tablas de referencia: Descripción de la información, específica del servicio, que por razones de diseño se intercambie en el servicio mediante su código correspondiente. Especificar que aquellas tablas de referencias comunes para más de un servicio dentro del mismo Sistema vendrán informados en el documento de elementos comunes, cuya plantilla es DGPD_NORM_Plantilla Elementos Comunes, en su última versión.
• Gestión de errores: Para cada uno de los error que puede devolver el servicio, se define el código, la descripción del error y la recomendación para subsanar el mismo.
• Ejemplos: Ejemplos de todas las funcionalidades que contienen las operaciones del servicio.
• Información complementaria como anexos, glosario y referencias. 

Adicionalmente a la cumplimentación de este documento se ha de adjuntar el WSDL en servicios SOAP, y los esquemas de datos utilizados (JSON o XSD).

3.4. Elementos Comunes

Cada sistema deberá disponer de un documento que recoja los elementos comunes  para todos los sistemas web que publique. De esta forma, en el contrato del servicio aparecerá únicamente la información especifica del servicio mientras que aquellos aspectos que sean comunes para los distintos servicios Web podrá consultarse en el documento que se generó a partir de la plantilla DGPD_NORM_Plantilla Elementos Comunes, en su última versión, y que tiene la siguiente estructura:

• Tipos de datos: Recoge aquellos datos estructurados comunes a varios servicios Web del Sistema en cuestión.
• Tablas maestras: Recoge las tablas maestras del sistema que son compartidas por varios servicios web. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 12 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital
• Gestión errores: muestra los errores que pueden darse de manera genérica en varios servicios del Sistema.

3.5. Comunicación SSL/TLS

Se establece el uso de SSL/TLS como protocolo de comunicación para aquellos servicios que se consuman o se ofrezcan tanto en sistemas ubicados dentro de la CHAP como los ubicados fuera de la misma. Este protocolo facilita la comunicación cifrada permitiendo la confidencialidad del dato/mensaje intercambiado entre dos sistemas. De esta forma, se proporciona seguridad ante aquellos accesos a servicios que se realicen desde cualquier punto con acceso a internet (cafeterías, aeropuertos, …) cuyas conexiones no siempre encriptan las comunicaciones y resultan fácilmente espiados o falsificados si son interceptadas las credenciales de autenticación.

SERVICIOS SOAP

SOAP (siglas de Simple Object Access Protocol) es un protocolo estándar que define cómo dos objetos en diferentes procesos pueden comunicarse por medio de intercambio de datos XML. SOAP es un paradigma de mensajería de una dirección sin estado, que puede ser utilizado para formar protocolos más complejos y completos según las necesidades de las aplicaciones que lo implementan. Por ello, se definirán como servicios SOAP aquellos servicios que necesiten un mecanismo de seguridad complejo.

4.1. Reglas de implementación para Servicios SOAP

4.1.1. WSDL

WSDL (Web Services Description Language) es un XML que se utiliza para describir la interfaz pública de los Servicios Web de forma estandarizada.

4.1.1.1. Definición WSDL

Un documento WSDL describe tres propiedades fundamentales de un servicio web:

• Las operaciones soportadas y qué mensajes las activan.
  • El formato de los mensajes.
  • Los tipos de datos especiales que se envíen se incluyen en el archivo WSDL en forma de XML Schema.
• El protocolo de comunicación en el que se envía el mensaje. 
• La forma en qué cada operación se compone de mensajes formateados de una forma específica y transmitidos por un protocolo concreto de red Un WSDL dispone de dos partes; la parte abstracta y la parte concreta:

• En la parte abstracta se incluye: 
  • Types: Esta etiqueta define las estructuras de datos que se utilizarán para construir los mensajes de petición como de respuesta. Estas estructuras de datos pueden construirse con cualquier lenguaje, pero lo más normal es hacerlo con XML Schema. 
  • Message: Describe los mensajes que se van a intercambiar entre el cliente y el Servicio Web. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 14 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital Un mensaje puede estar dividido en varias partes, por ejemplo, si en un mensaje queremos enviar datos y una imagen. 
  • PortType: Define el conjunto de operaciones que soporta el Servicio Web. Una operación no es más que un grupo de mensajes que serán intercambiados. Cada operación puede enviar o recibir al menos un mensaje cada vez.
• En la parte concreta se incluye: 
  • Binding: Describe como formatear los mensajes para interactuar con un Servicio determinado. WSDL no define un estándar para formatear mensajes. Para ello utilizar la extensibilidad para definir como intercambiar los mensajes usando SOAP, HTTP, MIME, etc… 
  • Services: Este elemento indica donde se encuentra el Servicio usando la etiqueta. Cada etiqueta define el formato de los mensajes, y la dirección donde se encuentra el servicio que acepta mensajes en ese formato.

Cada Servicio Web ha de disponer y publicar el WSDL que han de ser auto documentados, es decir han de contener detalle explicativo del servicio, de las operaciones y todos los tipos de datos que describa. 

En el caso de que el Servicio Web incluya elementos como seguridad, Addressing, etc, el WSDL incluirá las políticas empleadas según se define en la especificación WSPolicy.

4.1.1.2. Namespaces

La definición de los namespaces dentro de los Servicios Web es un tema muy importante a tener en cuenta. Una correcta definición de los mismos favorece la reutilización y catalogación de los servicios y posibilita la creación de cierto tipo de servicios horizontales de enrutación y mediación. Se ha detectado que los ficheros de XSLT parecen tener un contador interno y una vez se supera este contador, acaba arrojando un error 500. Para evitar este error, como buenas prácticas en la creación de namespaces, se deberá hacer una correcta definición de los mismos, evitando la generación dinámica de nodos en el esquema. 

Los namespaces dentro de los WSDLs y esquemas empleados dentro de los Servicios Web, se normalizan dentro de MADEJA. Los namespaces deberán incluir una referencia a la Junta de Andalucía, Consejería, aplicación, servicio, componente y número de versión.

Para la definición de los namespaces se puede optar por emplear URIs basadas en URLs o urn. El formato recomendado por MADEJA y el obligatorio en los desarrollos en CHAP es el de urn, al ser más claro y requerir menos procesos de normalización que el de URLs. 

El formato y la descripción de los campos es el presentado a continuación.

4.1.2. Definición de servicios (Contract-First)

A la hora de desarrollar un Servicio Web el programador puede optar por desarrollarlos siguiendo la aproximación "Code-First" o la aproximación "ContractFirst". 

En la aproximación "Code-First", primero se codifica el código del servicio dentro del lenguaje de programación y después se genera el WSDL describiendo el servicio de forma automática, a través del framework de Servicios Web elegido. Esta opción presenta una serie de inconvenientes que desaconsejan su uso. El contrato del servicio está muy ligado a la implementación del mismo, de forma que un cambio en dicha implementación puede conllevar cambios en el WSDL. Además, el contrato está también muy ligado al framework de programación empleado, de forma que un cambio de framework o una actualización de versión del mismo, puede conllevar cambios en el WSDL, con las consiguientes implicaciones en los consumidores de dicho servicio.

En la opción "Contract-First", la idea es la contraria, primero se genera el WSDL y después se codifica el servicio. Esta opción carece de los inconvenientes de la opción anterior y aporta numerosas ventajas a la hora de desarrollar y mantener los Servicios Web. En esta opción hay que definir las operaciones, métodos y datos del negocio del servicio como fase inicial del análisis, para implementar posteriormente el código. Los diseños Contract-First permiten dar mayor robustez al servicio frente a variaciones. También mejora los aspectos de reusabilidad, rendimiento y versionado, haciendo que sea una de las características más habituales en el diseño de Servicios Web. Se debe tener en cuenta que el desarrollo de servicios con esta f ilosofía requiere un planteamiento y definición iniciales, tanto de los servicios, como de los datos que van a formar parte del mismo. Este esfuerzo en la definición redundará  en la mejora del servicio a proporcionar, una mayor claridad en el planteamiento y una independencia en cuanto a la lógica de negocio interna de la aplicación. 

Por todo ello, es obligatorio que los Servicios Web desarrollados sigan la aproximación Contract-first.

4.1.3. Patrón de diseño XML Schema

Los esquemas XML que se utilicen junto a los descriptores de contratos de servicios web (WSDL) tendrán que cumplir con las especificaciones WS-I Basic Profile, con el propósito de cumplir unos requisitos de interoperabilidad y asegurar la compatibilidad en las invocaciones entre los mismos. 

A la hora de diseñar el schema XSD, se han de crear tipos y elementos globales (a nivel raíz) para poder reutilizarlos, tanto a nivel de elementos XML como del WSDL. Un elemento global es cualquier hijo de un nodo o una referencia directa a uno de ellos.

4.1.4. Definición de atributos y operaciones

No se permiten servicios que expongan operaciones con parámetros de entrada y/o salida de tipo cadena de texto que lleven incrustado un archivo XML con toda la lógica asociada.

Este tipo de prácticas aumenta la complejidad de la capa de negocio al tener que interpretar dicho XML incrustado. En cuanto a la parte del consumidor, dificulta la comprensión del servicio al no estar basado en un estándar público, siendo más complicado el testeo y posterior tratamiento del mensaje en la capa de negocio de la aplicación. 

A nivel de orquestación en la Plataforma de Interoperabilidad, este tipo de prácticas complica el tratamiento de los mensajes enviados, así como la validación del mismo contra esquemas. 

Para evitar esta problemática se ha de eludir este tipo de prácticas en los servicios web y realizar la definición de esquemas precisos para cada uno de los elementos que van a viajar en la petición.

4.1.5. Intercambio de documentos a través de servicios

La trasmisión de ficheros mediante Servicios Web se debe realizar de una forma optimizada, o bien haciendo uso de MTOM o bien como attachments. 

MTOM es un mecanismo de optimización que proporciona una forma  efectiva y normalizada (por W3C) de transmitir ficheros, donde en lugar de proporcionar el contenido en el body codificado en Base64, envía los datos binarios como adjunto. Debe evitarse, en al medida de lo posible, la transmisión de ficheros sobre el body. 

4.1.6. Nomenclatura

A continuación se describen las reglas de nomenclatura para el desarrollo de servicios:

• El nombre del servicio debe describir lo mejor posible la funcionalidad. De esta forma, los desarrolladores y administradores de sistemas pueden predecir/intuir fácilmente la función del servicio basándose en su nombre. 

• Hay que tener en cuenta que se distingue entre mayúsculas y minúsculas. 

• Con respecto al nombre del servicio, debe utilizarse el estilo “CamelCase”, el cual es un estilo de escritura que se aplica a frases o palabras compuestas. El nombre se debe a que las mayúsculas a lo largo de una palabra en CamelCase se asemejan a las jorobas de un camello. Existen dos tipos de CamelCase: 

   ◦ UpperCamelCase, cuando la primera letra de cada una de las palabras es mayúscula. Ejemplo: EjemploDeUpperCamelCase. 

   ◦ lowerCamelCase, igual que la anterior con la excepción de que la primera letra es minúscula. Ejemplo: ejemploDeLowerCamelCase. Este estilo es el que se ha de usar. Ejemplo: consultaDatosUsuario en lugar de consulta_datos_usuario 

• Utilizar sólo caracteres alfanuméricos (no utilizar los caracteres .; : | _ ,). 

4.1.7. Versionado de servicios

Los Servicios Webs no son elementos inmutables en el tiempo, sino que están sujetos a cambios a lo largo de toda su vida. El componente distribuido de los Servicios Web hace que los cambios en su interfaz puedan repercutir en los consumidores, obligándoles incluso a volver a implementar su interfaz con el servicio.

Todo esto desemboca en la necesidad de definir una política de versionado de los Servicios Web, que aborde la creación de reglas que regulen la evolución de los mismos. Para ello se debe identificar los tipos de cambios que se realizan en un servicio y tener en cuenta el impacto de dichos cambios.

A continuación se detallan los diversos tipos de cambios que se han establecido para un Servicio Web:

• Revisión: Cambio que se produce cuando se arregla algún bug o problema interno. Estos cambios no alteran el contrato del servicio. 

• Versión Menor: Son cambios que mantienen la compatibilidad, es decir, son cambios en la implementación que no modifican la funcionalidad actual en el servicio y que por tanto no obligan a los consumidores de dicho servicio a volver implementar la interfaz. Normas de desarrollo de servicios web Normas y buenas prácticas para el desarrollo de servicios web Página 19 de 26 Versión: <v01r04>Consejería de la Presidencia, Interior, Diálogo Social y Simplificación Administrativa Agencia Digital de Andalucía Dirección General de Estrategia Digital 

• Versión Mayor: Son cambios que hacen incompatibles el servicio, es decir, son cambios que modifican la funcionalidad del servicio y que, por tanto, obligan a volver a implementar la interfaz a los consumidores de dicho servicio. 

Como se ha comentado en el apartado de nomenclatura, el nombre del servicio incluye el número de versión, el cual no variará ante los cambios con compatibilidad hacia atrás (cambios menores o revisión), y que se incrementaría en caso contrario. 

   Ejemplo: v01/nombreServicio      v02/nombreServicio

Para permitir que los clientes de los servicios se adapten ante cambios de versión se seguirán las siguientes reglas:

• Los cambios de versiones menores no implicarán cambio de versión del servicio pero han de ser documentados en el WSDL y requerirán una actualización del contrato del servicio. El proveedor del servicio tendrá que comunicarlos a los clientes del servicio para que estos puedan decidir si hacer uso de las funcionalidades añadidas. 

• Los cambios de versión mayor implicarán cambio de versión del servicio. Para permitir la adaptación de los clientes a las nuevas versiones se permitirá la existencia de hasta dos versiones del servicio funcionando en paralelo. La OT-I garantizará el acceso al servicio anterior durante un plazo máximo de dos meses, tiempo en el que el cliente del servicio debe tener desarrollado la nueva versión del servicio. 

• Los cambios de versiones de los servicios han de ser notificados a los clientes, previa actualización del WSDL y del contrato del servicio. En casos excepcionales en los que sea necesario mantener mas de dos versiones en paralelo de un servicio debido a que un cliente no pueda adaptarse, se trasladará a la OT-I. 

Esta misma política de versionado se ha de seguir para el versionado de esquemas de datos.

4.1.7.1. Versión menor

Son pequeñas modificaciones que afectan al contrato del Servicio pero son compatibles con la versión anterior.

Ejemplos de estas modificaciones son: 

Inclusión de un atributo no obligatorio a los datos de entrada

Añadir un nuevo método al Servicio

4.1.7.2. Versión mayor

Son modificaciones incompatibles con el contrato anterior. Es un cambio que si afecta a la compatibilidad hacia atrás del servicio,  por lo que se deberá incrementar el número de versión del nombre del servicio. 

Para permitir la adaptación de los clientes de esta nueva versión del servicio se tendrá que mantener en paralelo la versión anterior del servicio durante el tiempo que se acuerde con la OT-I. Durante este tiempo se adaptarán los consumidores del servicio a la nueva versión. 

Es importante destacar que un cambio de versión de un Esquema de Datos utilizado por un Servicio implicará el cambio de versión también del servicio.

Ejemplos de estas modificaciones son:

Eliminación de un método.

Renombrado de un método.

Cambio en los parámetros de un método.

Cambios en un tipo de datos existente dentro del esquema.

Transformar un campo opcional a obligatorio.

4.1.8. Versionado de especificación

No todas las especificaciones son compatibles hacía atrás. Por ejemplo, SOAP 1.2 no es totalmente compatible con SOAP 1.1 o SOAP 1.0. Un nodo que cumpla con SOAP 1.1 generara un mensaje SOAP Fault indicando que la versión no coincide si le llega un mensaje SOAP 1.2. Un nodo utilizando SOAP 1.2 tendrá la opción de procesar el mensaje, o generar un SOAP Fault. 

Por lo que será necesario desarrollar utilizando siempre la misma versión de especificación o versiones compatibles.

4.1.9. Equilibrio entre servicios y operaciones

Es habitual encontrarse con las siguientes situaciones a la hora de desarrollar servicios web: 

• Un único servicio, con multitud de operaciones. 

• Servicios por operación. 

Ambos extremos son perjudiciales. Se deben diseñar servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables. 

Puede tomarse como un buen punto de partida el definir un Servicio Web  por cada servicio de negocio identificado.

4.1.10. Granularidad gruesa

A la hora de diseñar las operaciones, es más eficiente utilizar un único mensaje de gran tamaño, que su equivalente en múltiples mensajes. Uno de los errores habituales cuando se trabaja con WSDL es definir operaciones con excesiva granularidad. Es mejor definir servicios de grano-grueso y que los servicios estén orientados al negocio mas que a las interfases de programación. No se debe definir una operación de servicio por cada método Java que se quiera exponer. Siempre hay que pensar en las necesidades desde la perspectiva del negocio mas que en las técnicas a la hora de exponer los servicios.

4.1.11. Context-Type

El campo Context-type de la cabecera del mensaje, define el tipo de datos de cada parte como type/subtype. 

Uno de los valores más comunes que puede adoptar el campo ContextType es “text/xml”. Sin embargo, no está soportado en SOAP 1.2, por lo que el valor que debe configurarse para el desarrollo de Servicios Web es “application/soap” o “application/soap+xml”.

GESTIÓN DE ERRORES

La normativa relativa a la gestión de errores de los Servicios Web está recogida en el documento DGPD_NORM_Politica de Gestion de errores, en su última versión.

BIBLIOGRAFIA Y REFERENCIAS