De OData/XML a JSON limpio: mediación de payloads en SAP API Management

Hay una escena que se repite en casi todos los proyectos de integración con SAP. Tienes un backend que funciona perfectamente, normalmente un servicio OData de S/4HANA que devuelve XML, y al otro lado un equipo de desarrollo frontend o un partner que te pide lo mismo de siempre: «¿nos lo podéis dar en JSON?». El backend no se va a cambiar (ni debe), pero el consumidor tampoco va a tragar XML. Entre ambos hay un sitio donde resolver el problema: la capa de mediación del API Proxy.

En este artículo vemos cómo transformar payloads en SAP API Management sin tocar ni una línea del backend, qué políticas intervienen y en qué orden colocarlas. Usamos un caso real: exponer un servicio de productos de S/4HANA, que habla OData v2 en XML, como una API REST que entrega JSON.

El problema: dos formatos que no se entienden

OData v2, el protocolo que sigue usando una gran parte del ecosistema SAP, devuelve por defecto un XML verboso y anidado: envoltorios <entry>, elementos <content>, espacios de nombres m: y d: por todas partes. Es perfectamente válido, pero ningún desarrollador de una app móvil o de un frontend moderno quiere lidiar con eso. Lo que esperan es un JSON plano y directo.

El mismo producto: a la izquierda como lo entrega S/4HANA, a la derecha como lo quiere el consumidor.

La tentación es resolverlo en el backend o crear un servicio intermedio a medida. Ambas opciones añaden coste y mantenimiento. La alternativa correcta en una arquitectura de gestión de APIs es delegar esa traducción en el proxy, que está justamente para eso.

Mediación: traducir en ambos sentidos

La mediación es la familia de políticas de API Management que transforma, enriquece o filtra el mensaje mientras viaja por el proxy. La clave está en que actúa en los dos sentidos del flujo: en la petición (lo que el cliente manda hacia el backend) y en la respuesta (lo que el backend devuelve hacia el cliente).

El proxy traduce JSON a XML en la petición y XML a JSON en la respuesta. El backend siempre ve XML; el cliente, siempre JSON.

Para nuestro caso de productos, el escenario más habitual es de solo lectura (GET), así que el peso recae en la respuesta. Pero en cuanto entran operaciones de escritura (POST, PUT), el cliente enviará JSON y habrá que convertirlo a XML antes de llegar a S/4HANA. Por eso conviene entender la mediación como algo bidireccional desde el principio.

Las políticas que vas a usar de verdad

API Management ofrece muchas políticas de mediación, pero en el día a día casi todo se resuelve con cuatro.

El cuarteto de mediación que cubre la mayoría de escenarios reales.

JSON to XML y XML to JSON

Son las dos caras de la misma moneda. XML to JSON se coloca en el flujo de respuesta y convierte el XML del backend en JSON antes de devolverlo. JSON to XML hace lo contrario en el flujo de petición. Conviene saber que la conversión automática genera un JSON correcto, pero no necesariamente bonito: los espacios de nombres y los envoltorios de OData se traducen de forma literal. Por eso raramente van solas.

Assign Message

Es el cuchillo suizo de la mediación. Permite crear, modificar o eliminar partes del mensaje: cabeceras HTTP, query parameters, el cuerpo y variables de flujo. En nuestro caso sirve, por ejemplo, para añadir el query parameter $format=json hacia el backend cuando el servicio OData lo soporta, o para limpiar cabeceras técnicas que no queremos exponer al cliente.

Extract Variables

Lee datos del mensaje (de la URL, de una cabecera o del propio body) y los guarda en variables de flujo que después usan otras políticas. Es lo que te permite, por ejemplo, capturar un identificador de producto de la ruta y reutilizarlo más adelante en el flujo.

XSL Transform

Cuando la estructura del XML es demasiado compleja para una conversión directa, XSL Transform aplica una hoja de estilo XSLT que reestructura el documento con todo el control. Es más potente, pero también más costosa de mantener: úsala solo cuando la conversión simple no llega.

El orden importa: cómo encadenar las políticas

Una política mal colocada no rompe el proxy, pero hace trabajo inútil o produce un resultado inesperado. Esta es una secuencia razonable para nuestra API de productos.

Qué se ejecuta en el flujo de petición y qué en el de respuesta.

En el flujo de petición:

• Verify API Key valida primero el acceso. Si la clave no es válida, nos ahorramos todo lo demás.
• Extract Variables captura los datos de la petición que vamos a necesitar.
• Assign Message ajusta cabeceras y parámetros hacia el backend.
• JSON to XML convierte el cuerpo a XML solo si la operación es de escritura.

En el flujo de respuesta:

• XML to JSON transforma la respuesta del backend a JSON.
• Assign Message limpia el JSON resultante: elimina envoltorios sobrantes y renombra campos para que la salida sea la que prometemos en la documentación.
• Response Cache guarda el resultado para peticiones repetidas, lo que baja la latencia y descarga al backend.

El detalle fino está en ese Assign Message de la respuesta. La conversión automática deja un JSON con la estructura de OData; es ahí donde le damos la forma limpia que el consumidor espera. Sin ese paso, entregas un JSON técnicamente correcto pero incómodo de consumir.

Buenas prácticas y errores frecuentes

No confíes en la conversión automática sin revisarla.
XML to JSON produce un JSON funcional, pero arrastra la estructura de OData. Revisa siempre la salida real y límpiala con Assign Message hasta que coincida con el contrato que publicas en el Developer Hub.

Aprovecha $format=json cuando el backend lo soporte.
Muchos servicios OData de SAP devuelven JSON de forma nativa si añades el parámetro $format=json. Cuando es el caso, te ahorras la política de conversión y reduces latencia. Comprueba siempre esa opción antes de montar la transformación completa.

Cuida los errores del backend.
Cuando S/4HANA devuelve un error, también lo hace en XML. Si solo conviertes la respuesta correcta, el cliente recibirá un error en un formato distinto al esperado. Asegúrate de tratar también el flujo de error y devolver siempre JSON coherente.

No metas lógica de negocio en la mediación.
La mediación traduce y da forma al mensaje. Si te ves calculando precios, aplicando reglas complejas o combinando varias llamadas, ese trabajo pertenece a Cloud Integration, no al proxy. Mantén la capa de API ligera.

Conclusión

La mediación es lo que permite que un backend SAP clásico se presente al mundo como una API moderna. Con cuatro políticas bien combinadas (conversión de formato, Assign Message, Extract Variables y, cuando hace falta, XSL Transform) se cubre la gran mayoría de escenarios sin tocar el sistema de origen ni montar servicios intermedios a medida.

La regla que conviene grabar: el backend habla su idioma, el cliente el suyo, y el proxy traduce. Cuanto más limpia y declarativa sea esa traducción, más fácil será mantener la API cuando cambien los consumidores o evolucione el backend.

En la siguiente entrega veremos cómo devolver errores profesionales en tus APIs con Raise Fault y FaultRules: por qué nunca debes dejar que un error crudo del backend llegue al cliente y cómo construir respuestas de error coherentes en todo el proxy.

Fuentes

• SAP Help Portal · API Management · JSON to XML / XML to JSON Policy.
• SAP Help Portal · API Management · Assign Message and Extract Variables.
• SAP Help Portal · Mediation Policies Overview.
• Curso SAP API Management & Open Connectors · Logali Group · Bloque II – Mediation Policies.