Algunas buenas prácticas para el diseño de servicios web.

Estuve buscando en internet algo al respecto y me topé con un post del 2009 donde se detallan muy claramente unas cuantas buenas prácticas.
Aquí se las dejo:

1. 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.
2. 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í).
3. 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 múltiples mensajes.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. 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.
11. Si necesitas enviar ficheros adjuntos (attachments), hazlo a nivel de http attachment y no como un elemento del mensaje XML.
12. Automatiza el proceso de generar el Skeleton y las clases OXM de mensajes del servicio web a partir del WSDL (wsdl2code).
13. 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.
14. Guarda log de los mensajes de entrada y salida junto con datos del cliente (ip, usuario), a nivel de fichero o base de datos.
15. 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.

Posted in buenas prácticas, diseño servicios, servicios web, WSDL