Buenas practicas para desarrollar servicios web SOAP

Como complemento a mi último post, Arquetipo de WSDL interoperable, he decidido publicar este post con varias buenas prácticas para desarrollar servicios web SOAP. Como siempre, son sólo buenas prácticas según mi criterio, conocimiento y experiencia.

  • Analiza qué servicios web y con qué operaciones hay que desarrollar. Parece de perogrullo, pero es uno de los fallos más repetidos. Según mi experiencia suelen darse 2 esquemas a la hora de desarrollar servicios web: (i) el servicio web dios con todas las operaciones para él y (ii) un servicio web por operación. Ambos son malos. El primero incluso peor. Así que piensa y diseña servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables.
  • Escribe tu mismo el fichero WSDL (Contract-First). Es el interfaz, el contrato y, en definitiva, la clave para una interoperabilidad real e independiente de la tecnología. Además los generadores de WSDL pueden introducir dependencias con una tecnología concreta. Por eso merece la pena aprender a escribir WSDL (aquí) y schemas XSD (aquí).
  • A la hora de diseñar el interfaz de las operaciones, ten siempre en cuenta que es mucho más eficiente un único mensaje enorme que el equivalente en multiples mensajes.
  • Sé coherente con la nomenclatura de namespaces de la organización. No hay nada que de peor impresión que un servicio web que no ha cuidado los namespaces.
  • El WSDL debe ser compatible con el WS-I Basic Profile. El WS-I Basic Profile es un conjunto de especificaciones y buenas practicas definidas por la industria para obtener servicios web interoperables. Actualmente la última versión final publicada es la 1.1. Como mínimo, evita siempre los estilos RPC y sus tipos de datos no XML (SoapArrays), en su lugar usa el estilo Document/literal.
  • Usa http://localhost:puerto como dirección url del endpoint y deja que sea el motor de webservices el encargado de sustituirla por la real. Así evitarás tener un fichero WSDL por entorno.
  • Separa la definición de los mensajes del fichero WSDL. Para ello, diseña por separado un schema XSD donde se definan los mensajes y que sea importado por el fichero WSDL. Las principales ventajas son (1) reduce el tamaño/complejidad del WSDL, (2) permite utilizar editores especializados para el diseño del schema XSD y (3) permite reutilizar schemas y namespaces.
  • Define los mensajes de forma detallada mediante las restricciones de los schemas XSD. De esta forma podrás validar los mensajes a nivel de XML mediante el api XML u OXM que uses, sin necesidad de implementar código propio.
  • A la hora de diseñar el schema XSD, crea tipos y elementos globales (a nivel raíz) para poder reutilizarlos, tanto a nivel de elementos XML como clases del lenguaje de implementación del servicio web.
  • Además, usa minOccurs=0 para definir un elemento como opcional y nillable=true para indicar que un elemento puede ser vacío pero siempre estará presente en el mensaje XML. Ojo, no es lo mismo.
  • Si necesitas enviar ficheros adjuntos (attachments), hazlo a nivel de http attachment y no como un elemento del mensaje XML.
  • Automatiza el proceso de generar el Skeleton y las clases OXM de mensajes del servicio web a partir del WSDL (wsdl2code).
  • Para realizar pruebas unitarias del servicio web no necesitas desplegarlo, puedes programar tus tests a nivel de la clase Skeleton. Ahorraras mucho tiempo y ya desplegarás para las pruebas de integración o alguna demo.
  • Guarda log de los mensajes de entrada y salida junto con datos del cliente (ip, usuario), a nivel de fichero o base de datos.
  • Redacta un documento Guía de pruebas de integración que sea completo e incluya casos de error y no sólo los casos básicos.

12 comentarios :: Buenas practicas para desarrollar servicios web SOAP

  1. Hola,

    me ha aparecido muy interesante tu blog y sobre todo rdtr articulo.

    Podias aclarar mas el tema "motor de webservices el encargado de sustituirla por la real."

    he desarrollado un web service , pero tengo el problema schemalocation y soap address location hacen refrencia a una direccion local y tienen que acceder a través de firewall

    Estoy usando metro y sunone appserver(Glasfishh)

    Gracias

  2. Hola jddr70. Me alegro que te haya sido útil.

    Yo siempre uso como soap address http://localhost:8080 y luego es Axis2 (Axis tb lo hacía) cuando despliega el webservice el que lo cambia por la url real.
    Es el comportamiento por defecto de Axis2, aunque existe un parametro de configuración para modificarlo.

    Ahora ya con metro ni idea...

    Respecto al schemalocation, si usas una url porque estas publicando los schemas, mi recomendación es que siempre uses un nombre de maquina en la url. Así podrás mapearlo a la ip conveniente en el fichero hosts de tu máquina para que apunte a desarrollo, pruebas, etc.

    Espero haberte ayudado.

  3. Hola:
    creo tener el mismo problema de jddr70.
    En mi servicio web esta definido el soap adress con http://localhost:8080

    pero al publicarlo en mi servidor de pruebas con salida a internet y firewall me cambia esta ip por la LOCAL y mis clientes capturan el wsdl, esta ip a ellos no les sirve no encuentran el servidor.

    ¿Cómo puedo cambiar el parámetro soap adress? para que me tome la ip publica de mi servidor.

    Espero me puedan ayudar,
    Gracias.

  4. No puedes. El motor de webservices no es adivino :-)

    Si quieres forzar la dirección, debe ser en el WSDL.

    Pero entonces tendrás el problema de mantener un WSDL para cada entorno que uses.

    Si lo piensas, verás que en realidad no tienes ningún problema. Sólo debes pasar la dirección del endpoint de cada entorno a los que vayan a desarrollar un cliente.
    Cuando desarrollas un cliente, la dirección del endpoint siempre es un parametro de configuración para poder reutilizar el código en todos los entornos.

  5. Hola,
    Antes que nada, gracias por compartir conocimientos, muy interesante tema.
    Lo que planteas es un diseño de WS top-down, pero que pasa cuando quiero desarollar los WS en JEE para integrarlos con EJB3? Entiendo que parfa esto basta con hacer algunas declaraciones en el codigo de los componentes EJB3, luego al compilar se construye y despliega automáticamente el Wsdl. ¿Cual es tu opinión?
    "solo"
    Gracias

  6. Hola Luis.

    Bueno, es una opción claro. Como digo en el post, para mi es una buena práctica realizar un desarrollo Contract-First (Top-Down) porque tienes el control del interfaz WSDL y no dependes del generador de WSDL. El WSDL es lo más importante en un WS porque será a partir de él con lo que se construirán los clientes. No sería la primera vez que un WSDL autogenerado luego no funciona con algunas tecnologias.

    Pero al final es como todo, debes tomar la decisión de qué estilo seguir teniendo en cuenta (1)la complejidad del interfaz, (2)el tiempo de desarrollo, (3)la tecnologia de los clientes, (4)si tienes control sobre su desarrollo y (5)la mantenibilidad que necesitas.

    Un saludo.

  7. Excelente post, creo que se debe hacer incapié en todos estos aspectos, que como bien dices, vienen dado en su mayoría por la experiencia en este campo.
    Slds
    A

  8. Gracias por la aportación, podrías explicar mas a detalle:

    A la hora de diseñar el interfaz de las operaciones, ten siempre en cuenta que es mucho más eficiente un único mensaje enorme que el equivalente en multiples mensajes.

    Gracias

  9. Hola Shivan.

    Lo que quería decir es que a veces existen operaciones que necesitan ser usadas en modo masivo. Especialmente aquellas que publican información.
    Entonces siempre es más eficiente hacer 1 llamada que devuelva muchisimos datos que muchas llamadas que devuelvan 1 dato.
    Aunque para ello tendrás que rediseñar la petición, siendo más flexible en los parámetros de entrada o permitiendo repetir parámetros.

    Esto es porque cada invocación tiene un coste fijo no despreciable, aunque sean invocaciones en la misma subred.

    Espero haberte aclarado.

  10. Interesante artículo contiene información importante, gracias por informarnos sobre este tema.

  11. Hola Cesar,
    me quede un poco confundido con el primer punto el cual mencions que sulene darc 2 tipos de esquemas, 1 el que lo tiene todo y 2 por operaciones, entonces tu mencionas "Así que piensa y diseña servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables." si me podrias explicar a que te refieres, de verdad agradeceria tu apoyo un saludo desde el Estado de Mexico

  12. Escribe tu mismo el fichero WSDL. Las url no funcionan. Estas son

    http://www.w3schools.com/xml/xml_wsdl.asp
    http://www.w3schools.com/xml/xml_schema.asp

    Saludos

Publicar un comentario