Parte 2: El XML rocks!

Una Interfaz de Programación de Aplicaciones (API en inglés) es una colección de procedimientos predefinidos para que un programa pueda usar a otro. En la Internet, una API hará posible que una computadora use a otra. Contrariamente al método del hacker explicado previamente, las APIs están destinadas a ser soportadas oficialmente por los propietarios de la aplicación web a través de documentación y soporte extensos. Tu script ya no intentará imitar de forma humana los nombres de variables y la URL del action, sino que más bien tomará su propia ruta para obtener datos del servidor.

Las mayoría de las APIs se basan en XML, que hace posible transferir datos estructurados a través de la web. Básicamente, en lugar de enviar variables POST simples al servidor y recibir HTML, tu petición enviará y recibirá datos XML limpios e inmutables.

Al inicio, no hay límite para imaginar y diseñar una API. Basándonos en los ejemplos de la parte 1, podemos imaginar la siguiente forma de solicitud y respuesta:

POST /submit HTTP/1.1
Host: api.community.com
Content-Length: 125
Content-Type: application/text-xml

<?xml version="1.0" encoding="UTF-8"?>
 <datos>
	<nombre>Juan</nombre>
	<ciudad>Guadalajara</ciudad>
	<edad>23</edad>
 </datos>

Nota: es muy comun diseñar la API de tal forma que las solicitudes se envíen a un subdominio como api.comunidad.com. De esta forma, las solicitudes al subdominio www se supone que son enviadas por seres humanos y devuelven respuestas HTML mientras que las solicitudes en el subdominio api se supone que son enviadas por computadoras y devuelven respuestas XML. También notemos que quité la extensión .php de la página de submit (envío): a través de la API, no estamos accesando a una página sino a un recurso.

HTTP/1.1 200 OK
Date: Tue, 17 Jun 2008 20:24:00 GMT
Content-Length: 111
Content-Type: application/text-xml

<?xml version="1.0" encoding="UTF-8"?>
  <datos>
    <nombre>Anna</nombre>
    <nombre>Lisa</nombre>
  </datos>

Programáticamente hablando, codificar la solicitud en PHP es posible usando cURL e interpretar la respuesta certamente sería más fácil usando SimpleXML (incluida en PHP5). Por lo tanto, implementar la llamada API anterior en PHP se vería así:

<?php

   // PASO 1: ENVIAR LA SOLICITUD
   $url = 'http://api.comunidad.com/submit';
   $header = array('Content-type: application/text-xml');
   $xml = '<?xml version="1.0" encoding="UTF-8"?><data><name>Joe</name>
           <city>Indianapolis</city><age>23</age</data>';
   $handle = curl_init();
   curl_setopt($handle, CURLOPT_URL, $url);
   curl_setopt($handle, CURLOPT_HTTPHEADER, $header);
   curl_setopt($handle, CURLOPT_POSTFIELDS, $xml);
   curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
   $response = curl_exec($handle);
   curl_close($handle);

   // PASO 2: INTERPRETAR EL RESULTADO E IMPRIMIR LOS NOMBRES
   $result = new SimpleXMLElement($response);
   $val = array();
   foreach ($result->nombre as $nombre) {
      $val[] = (string) $nombre;
   }
   print_r($values);

?>

Nots: en este script cURL tuve que especificar el encabezado Content-type para que nuestra solicitud fuera interpretada correctamente por el servidor. Pude haber usado algunas opciones más como CURLOPT_TIMEOUT, por ejemplo.

Usar una API es mejor que forzar un formulario web por 3 razones:

• La solicitud pasa por una ruta especial diseñada para computadoras que está claramente definida en el subdominio api.comunidad.com
• Los datos de la respuesta están estructurados de mejor forma y son más fáciles de interpretar que una página plana en HTML.
• Los desarrolladores de comunidad.com, deben comprometerse en mantener un formato XML constante para las respuestas XML que son entregadas a las máquinas: esto significa, por ejemplo, que no pueden drásticamente dejar de aceptar las etiquetas <ciudad> en las solicitudes, o cambiar <nombre> por <persona> en las etiquetas de la respuesta (o de lo contrario, podrían generar un terrible desastre en las aplicaciones de terceras partes que aprovechan su API).

Esta última razón se resume bien en la famosa nota de Joshua Bloch de Google sobre el diseño de APIs:

Las APIs públicas son para siempre – una oportunidad para hacerla bien.

En el ejemplo anterior, asumimos que los desarrolladores de comunidad.com crearon una API desde cero, inventando una estructura XML personalizada para solicitudes y respuestas. Cuando se trata de diseñar una API, la realidad es que los desarrolladores tienden a respetar algunas estructuras API existentes diseñadas específicamente para APIs de tal forma que la API sea más fácil de aprender y ser usada para desarrolladores de terceras partes.

Hoy en día, 3 estándares API son usados ampliamente en la web:

• REST (REpresentational State Transfer)
• XML-RPC (XML Remote Procedure Call)
• SOAP (Simple Object Access Protocol)

En los siguientes posts echaremos un ojo a estos tres estándares XML con ejemplos detallados de cómo enviar y recibir datos.

(Traducción realizada por Nokrosis, del post original de Nemetral)

Continuará…