Normativa de desarrollo de Servicio Web

En los siguiente enlaces se puede obtener el documento completo de las Normativas de Desarrollo de Servicios Web , así como buenas prácticas para el desarrollo en la Plataforma  de Interoperabilidad:

Normas comunes a todos los Servicios

Alcance del servicio Cada WS ha de tener una responsabilidad única y diferenciada.
Perfil de Integración. Se deben definir las interacciones entre los servicios que requieran integración.
Se recogerá en un documento que explique la solución de integración. Para ello, se hará uso de la plantilla “OTI_INT_Plantilla Perfil de Integración” que puede encontrarse en Plantillas de Documentación. 
Contrato del Servicio Web. Este contrato seguirá la plantilla “OTI_INT_Plantilla Contrato Servicio” Web que puede encontrarse en Plantillas de Documentación. 
Entregables susceptibles de entrega/revisión.
  • Perfil de Integración.
  • Contrato del Servicio.
  • Elementos comunes del contrato del Servicio Web.
  • Análisis SOA.
  • Plan de Pruebas Funcionales.
  • Plan de Pruebas de Integración.
  • Manual de Entrega
Política común de gestión de errores.
  • Errores de comunicación: Errores relativos al envío y aceptación de mensajes.
  • Errores de mensajería: Entrega, validación y procesamiento del mensaje recibido.
  • Errores funcionales.
  • Servicio de notificación de error.
Desarrollo de servicios.
  • Todo el desarrollo subido a la plataforma debe seguir los mismos criterios de nomenclatura, estructura y arquitectura.
  • Se debe usar control de versiones (Git o SVN).
  • Se deben aplicar políticas de reintentos para confirmar cual es el estado del backend.

Normas para los Servicios tipo SOAP

Archivo WSDL.

 
  • Debe ser autodocumentado.
  • Los namespaces están normalizados dentro de MADEJA.
Definición de servicios. Primero se generará el WSDL y posteriormente se codificará el servicio.
Patrón de diseño XML Schema. Se debe cumplir con las especificaciones WS-I Basic Profile.
Uso de mensajería XML. No está permitido incrustar un archivo XML como un parámetro de tipo String.
Intercambio de documentos a través de los servicios. Se debe hacer uso de MTOM, enviando los documentos como attachments de los mensajes SOAP.
Versionado de servicios y de esquemas de datos. Existen 3 tipos de cambios: revisión, versión menor, versión mayor.
Los cambios de versiones de los servicios han de ser notificados a los clientes.
Versionado de especificación. Será necesario desarrollar utilizando siempre la misma versión de especificación o versiones compatibles.
Equilibrio entre servicios y operaciones. Se deben diseñar servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables.
Gestión de errores en servicios web SOAP.
  • Errores desvinculados de la funcionalidad del servicio.
  • Errores funcionales: Se implementarán a través de un formato definido para ello.
Desarrollo de servicios SOAP. El servicio deberá estar dentro de la carpeta proxy-services y seguir el patrón:
[TIPO_DE_VISIBILIDAD]_[TIPO_DE_SEGURIDAD]_[GRUPO_DEL_SERVICIO]_[NOMBRE_DEL_SERVICIO]_V[X.Y.Z]

 

Normas para los Servicios tipo REST

Uso de los métodos HTTP.
  • GET: Obtener información sin cambiar estado del servidor.
  • POST: Únicamente para alta de nuevas entidades en el sistema.
  • PUT: Modificar recursos ya existentes.
  • DELETE: Para borrar un recurso del servidor.
Nomenclatura de los URIs.
  • Han de estar orientadas a la exposición de recursos.
  • Han de ser únicas.
  • Han de incluir la versión de la API.
Versionado.
  • El número de la versión del servicio constará de tres dígitos.
  • La versión del servicio se indicará en los siguientes puntos: URL del servicio, Cabecera “versión“ y Nombres de los componentes de la plataforma.
Mensajería a intercambiar. Todos los recursos a intercambiar en la mensajería de los servicios REST definidos en la Consejería deberán de hacer uso del formato de texto JSON.
Content-Type. En el caso de los servicios REST, esta cabecera deberá contener el valor “application/json”.
Gestión de errores en servicios web REST. La estructura debe incluir siempre los siguientes elementos:
  • Estado: Código del estado HTTP.
  • Tipo: Identificador del origen del mensaje.
  • Código: Código interno del error.

Documentación de servicios REST.

 Se debe realizar siguiendo la plantilla “OTI_INT_Plantilla Contrato” que puede encontrarse en
Desarrollo de servicios REST. El servicio deberá estar dentro de la carpeta api y seguir el patrón:
[TIPO_DE_VISIBILIDAD]_[TIPO_DE_SEGURIDAD]_[GRUPO_DEL_SERVICIO]_[NOMBRE_DEL_SERVICIO]_V[X.Y.Z]