XML-RPC es tan fácil de usar y muchos proyectos todavía están basados en él. Pero en algunos años ha surgido un nuevo protocolo: SOAP. SOAP es tradicionalmente considerado como la evolución del XML-RPC. Seleccionado por Google para su famosa Search API (ahora descontinuada), el protocolo SOAP es comúnmente considerado como más complejo que los mensajes panos de XML-RPC. De hecho, si entendiste XML-RPC, entonces no debes tener dificultad para entender SOAP también, siendo éste una abstración de XML-RPC.
Parte 5: SOAP: Sexy o No?
Como XML-RPC, SOAP es un protocolo para mensajes XML sobre HTTP. Empecemos con la estructura básica de un mensaje SOAP (sin encabezados HTTP por el momento):
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
<soap:Header>
...
</soap:Header>
<soap:Body>
...
</soap:Body>
</soap:Envelope>
Nota: como puedes ver, un mensaje SOAP está formado de un ‘Sobre’ (Envelope) conteniendo un Encabezado opcional y un Cuerpo obligatorio, No es necesario volverse loco con los nombres: básicamente puedes escoger el propio para cualquier solicitud SOAP. Mira los elementos de la etiqueta ‘Envelope’: En este ejemplo escogimos ’soap’ y tuvimos que indicar que este nombre ’soap’ sigue algunos estándares (las dos líneas literalmente significan “el nombre ’soap’ que usamos debe considerarse que está en el nombre SOAP normal y el nombre ’soap’ sigue algunos estándares para tipos de datos). En lugar de soap, pudimos haver usado ‘SOAP-ENV’, ‘env’, ’s’ así como ‘minombreesjuan’. Lo importante aquí es sólo declarar el nombre.
Ahora veamos una solicitud más realista de SOAP con encabezados HTTP y con un nombre distinto para el ‘envelope’, digamos una simple ’s’ como se usa para la API de Flickr. El elemento Header, al ser opcional, no lo usaremos aquí:
POST /soap HTTP/1.1
Host: api.community.com
User-agent: script
Content-type: text/xml
Content-length: 332
<?xml version=”1.0″?>
<s:Envelope
xmlns:s=”http://www.w3.org/2003/05/soap-envelope”
s:encodingStyle=”http://www.w3.org/2003/05/soap-encoding”>
<s:Body>
<a:GetMembersList xmlns:a=”http://api.community.com/soap”>
<age>23</age>
<city>Indianapolis</city>
</a:GetMembersList>
</s:Body>
</s:Envelope>
Nota: como puedes ver, los encabezados HTTP deben tener un Host, un User-agent y un Content-type establecido como text/xml. Ahora mira dentro del elemento Body: lo que hay ahí son datos específicos de la aplicación que deben ser identificados usando distintos nombres (aquí usamos el punto de entrada de la API SOAP del sitio community.com). Los desarrolladores tienen la completa libertad de definir qué es lo que va adentro. Aquí elegimos el nombre ‘a’ para todos estos datos específicos de la aplicación y describimos qué metodo tenía que ser llamado (ej. GetMemberList), junto con los parámetros de edad y ciudad.
Hasta ahora emos visto la estructura básica de una solicitud SOAP. Ahora así es como se vería una respuesta SOAP:
HTTP/1.1 200 OK
Content-type: text/xml
Content-length: 391
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
s:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
<s:Body>
<a:GetMembersListResponse xmlns:a="http://api.community.com/soap">
<members>
<member>Anna</member>
<member>Lisa</member>
</members>
</a:GetMembersListResponse>
</s:Body>
</s:Envelope>
Nota: pocas cosas han cambiado en la respuesta. El nombre del método ha cambiado (siguiendo la convención de añadir el sufijo “Response” al nombre del método de la solicitud) y los datos específicos de la aplicación también cambiaron (ahora regresa los nombres de dos miembros que tienen 23 años y viven en Indianapolis). Aparte de eso, todos los nombres y definiciones, siguen igual.
Hay que tener en cuenta que SOAP es todo sobre abstracción y que su complejidad es el precio de su flexibilidad. Por ejemplo, escogemos diseñar los datos específicos de la aplicación dentro del primer nodo (llamándolo a:GetMembersList) pero pudimos haber decidido también especificarlo junto con los datos en la siguiente forma (como en Flickr):
<a:Request xmlns:a="http://api.community.com/soap">
<method>GetMembersList</method>
<members>
<member>Anna</member>
<member>Lisa</member>
</members>
</a:Request>
En el ejemplo de solicitud de arriba, no especificamos los tipos de datos para los parámetros que enviamos junto con la solicitud. Sin entrar mucho en detalles, estea es la forma en que especificaríamos que <age> es un entero y <city> es una cadena:
POST /soap HTTP/1.1
Host: api.community.com
User-agent: script
Content-type: text/xml
Content-length: 482
<?xml version=”1.0″?>
<s:Envelope
xmlns:s=”http://www.w3.org/2003/05/soap-envelope”
s:encodingStyle=”http://www.w3.org/2003/05/soap-encoding”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
>
<s:Body>
<a:GetMembersList xmlns:a=”http://api.community.com/soap”>
<age xsi:type=”xsd:int”>23</age>
<city xsi:type=”xsd:string”>Indianapolis</city>
</a:GetMembersList>
</s:Body>
</s:Envelope>
Nota: como puedes ver, necesitamos dos especificaciones más definidas como atributos de la etiqueta Envelope. Primero necesitamos definir el nombre de la instancia de la estructura XML y luego el nombre de la estructura de los tipos de dato XML, y luego tenemos que agregar los atributos correspondientes a las etiquetas <age> y <city> (este último paso es claro).
ES todo para la introducción a SOAP. Así que.. ¿es sexy o no?
En muchos casos, SOAP es XML-RPC expandido. Si puedes quedarte con XML-RPC hazlo; no hay necesidad de empezar a usar SOAP. Por otro lado, si quieres expander el alcance de tu API o si necesitas tipos de datos muy específicos para tus solicitudes y respuestas, entonces usa SOAP. La elección final depende de las librerías disponibles: como SOAP es más complejo de manipular, usar una buena librería se torna más importante que para XML-RPC donde puedes hacer que tu PHP escupa directamente el XML.
—————————————-
Esta es una traducción lo más fiel posible de:
No Comments on "Conociendo las APIs (Parte 5)"