Nokrosis

En el post pasado revisamos los principios detrás de la arquitectura REST. En este post, como parte 4 de la serie dedicada a las API’s web, nos enfocaremos en XML-RPC que, contrariamente a REST, no se basa en principios generales, sino en una especificación sustancial de cómo debe darse formato a los mensajes XML transmitidos por HTTP.

Parte 4: Revision de XML-RPC

XML-RPC significa Llamada XML a Procedimiento Remoto, por sus siglas en inglés (XML Remote Procedure Call): una solicitud XML-RPC es una solicitud HTTP POST cuyo cuerpo esta formateado en XML y una respuesta XML-RPC es un archivo XML retornado por el servidor. Contrariamente a REST, el método llamado por una solicitud XML-RPC no aparece en la URL sino que aparece en el POST del cuerpo de la solicitud XML, entre las etiquetas <methodName>. Por lo tanto, XML-RPC funciona basado en un punto simple de entrada que es una URL única que debe ser llamada cuando se usa XML-RPC.

Antes de echarnos un clavado en las especificaciones de XML-RPC, así es como nuestra solicitud favorita (la que hemos estado usando) hecha a la API de community.com podría estar diseñada .

POST /xmlrpc HTTP/1.1
Host: api.community.com
User-agent: script
Content-type: text/xml
Content-length: 243

<?xml version=”1.0″?>
<methodCall>
  <methodName>community.members.getList</methodName>
  <params>
    <param><value><int>23</int></value></param>
    <param><value><string>Indianapolis</string></value></param>
  </params>
</methodCall>

Nota: hay muchos detalles importantes en esta solicitud de ejemplo, primero, decidimos usar http://api.community.com/xmlrpc/ como el punto simple de entrada. Entonces, XML-RPC requiere un User-agent (puede ser el nombre de la librería que estas usando, el nombre de tu script o el nombre de tu perro ) y un Content-type establecido como text/xml. Finalmente, los nombres de los metodos deben ser únicos: nosotros simplemente llamamos a este método getList, pudimos haber enfrentado dificultades al diseñar la solicitud para obtener, por ejemplo, ciudades en lugar de miembros. Es por esto por lo que usamos un prefijo en el nombre del método el cual es community.members  para tener presente que estamos usando la API de community.com y que estamos buscando miembros.

Y esta sería una respuesta exitosa:

HTTP/1.1 200 OK
Date: Tue, 01 Jul 2008 15:22:00 GMT
Content-Length: 313
Content-Type: text/xml
Connection: close

<?xml version=”1.0″?>
<methodResponse>
  <params>
    <param>
      <value>
        <array>
          <data>
            <value><string>Anna</string></value>
            <value><string>Lisa</string></value>
          </data>
        </array>
      </value>
    </param>
  </params>
</methodResponse>

Ahora si asumimos que hubo algunos problemas al transmitir o procesar la solicitud, así estaría formateada una respuesta de error:

HTTP/1.1 200 OK
Date: Tue, 01 Jul 2008 15:22:00 GMT
Content-Length: 384 
Content-Type: text/xml
Connection: close

<?xml version=”1.0″?>
<methodResponse>
  <fault>
    <value>
      <struct>
        <member>
          <name>faultCode</name>
          <value><int>1</int></value>
        </member>
        <member>
          <name>faultString</name>
          <value><string>Invalid request.</string></value>
        </member>
      </struct>
    </value>
  </fault>
</methodResponse>

Nota: no hay una especificación oficial para los códigos de error y los mensajes de error. Cada diseñador de la API debe concientemente crear códigos de error y mensajes de error para cada posible escenario. Aunque, se puede encontrar un intento de hacer los códigos de error más oficiales en esta página [en].

Esto es típico del protocolo XML-RPC: en lugar de confiar en un estándar específico, XML-RPC agrega una nueva capa de abstracción. Una llamada con REST pudo haber usado la herramienta de estado HTTP (por ejemplo:HTTP/1.1 400 Bad Request ) para notificar al cliente que la solicitud no funcionó; en lugar de esto, XML-RPC claramente sobreescribe el HTTP y pone el mensaje de error en la misma respuesta XML enviada. De hecho, el estado HTTP de la respuesta sigue siendo HTTP/1.1 200 OK aún cuando la respuesta resulto un fracaso.

Los tres ejemplos anteriores ilustran cómo se ve de ambas formas el XML-RPC en cuanto a solicitudes y respuestas. La estructura interna es fácil de adivinar: una solicitud debe estar contenida en la etiqueta <methodCall> y <params> (parámetros) opcionales. Simétricamente, una respuesta debe estar contenida entre la etiqueta <methodResponse> y especificar los <params> opcionales. Los parámetros están contenidos en las etiquetas <params> y cada parámetro debe estar entre las etiquetas <param> y <value>, y luego etiquetas correspondientes al tipo de dato. Por ejemplo un parámetro entero sería como esto: <param><value><int>23</int></value></param>.

XML-RPC define varios tipos de datos:

• int o i4: enteros de 32-bit (ej. <int>23</int> o <i4>23</i4>)
• double: números de punto flotante de 64-bit (ej. <double>2.7812</double>)
• boolean: Booleano (verdadero (1) o falso (0): ej. <boolean>1</boolean>)
• string: texto ASCII o Unicode (ej. <string>Hola Mundo!</string>)
• dateTime.iso8601: una cadena ‘datetime’ (ej. <dateTime.iso8601>20080701T15:22:00</dateTime.iso8601>)
• base64: información codificada en base64 (ej. <base64>SGVsbG8gV29ybGQh</base64>)

Y dos tipos de datos elaborados:

• array: como semuestra en el ‘ejemplo de respuesta exitosa’ arriba, los arreglos encapsulan datos en etiquetas <data> con tantos sub-objetos <value> como valores hay en el arreglo (junto con sus tipos de datos)
• struct: como se muestra en el ‘ejemplo de respuesta fallida’ arriba, los datos estructurados están compuestos por <members>, cada uno de ellos con un <name> y un <value> con un tipo de dato específico (un poco como los arreglos asociativos en PHP)

Nota: ambos  tipos de elementos struct y array son recursivos (p.ej. un elemento ‘struct’ puede contener un arreglo que contiene elementos struct, etc.): esto abre un sinfín de posibilidades para formato de datos.

En cuanto a programación, crear clietnes XML-RPC y servidores usando PHP y utilizando cURL y SimpleXML no es absolutamente nada complicado comparado con los códigos explicados en las partes 1, 2 y 3. Sólo cambia la sintaxis XML. También hay que notar que hay extensiones específicas para usar XML-RPC (más información en php.net).

Conociendo las API’s continúa en mi siguiente post con una rápida revision al sucesor de XML-RPC: SOAP.

Trackback URL