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:

The pursuit of APIness (Part 5)

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.

————————————

En la parte 2, vimos cómo se puede diseñar una estructura de API basada en XML par aun sitio ficticio (comunidad.com) permitiendo a los desarrolladores de terceras partes obtener acceso a los miembros de una cierta edad y viviendo en una cierta ciudad. El problema era: ¿es realmente buena idea permitir que cualquier aplicación web o sitio web diseñe su propia API? Es hora de presentar las 3 principales estructuras API: REST, XML-RPC y SOAP.

Parte 3: Let’s take a REST [es: Tomemos un 'descanso']

REST (REpresentational State Transfer) [Transferencia de Estado Representacional] actualmente es más que una simple estructura API. Cuando acuñó este concepto, Roy Fielding describió un completo estilo de arcitectura de software basado en:

• Limitaciones del protocolo: el protocolo debe ser cliente-servidor, sin estado, cacheable, multicapa, y permitir código sobre demanda.
• Recursos: Los recursos son elementos de información fundamentales en los que se pueden realizar operaciones (representar, vincular, modificar, incluir, buscar, cachear, etc.)
• Sintaxis universal: los recursos son unicamente accesibles usando una sintaxis universal.
• Representación: Los recursos no son datos y por lo tanto deben ser representados (a través de imagenes, HTML o contenido de cualquier tipo)
• Interfaz uniforme: La transferencia de estado es ejecutada a través de operaciones y tipos de conenidos bien definidos.

Un buen ejemplo de arquitectura REST podría ser la WEB: El HTTP es cliente-servidor, cacheable, multicapa, sin estado (sin tomar en cuenta cookies o sesiones), capaz de llevar código sobre demanda (Javascript o applets Java) y accesa a recursos a través de una interfaz uniforme (Métodos HTTP como GET/POST/PUT/DELETE, tipos de contenido MIME, Encabezados y URI). Así, HTTP puede ser usado más o menos como REST y podemos imaginar otras arquitecturas de tipo REST además de HTTP.

Apliquemos ahora los principios REST a las piezas de código que escribimos en la parte 2. Una API REST no debe cumplir un formato XML establecido, pero sí un estilo de arquitectura. Entonces así es como podríamos reescribir nuestra llamada API con REST, por ejemplo usando el potencial de las URIs y métodos HTTP.

GET /miembros?edad=23&ciudad=Indianapolis HTTP/1.1
Host: api.comunidad.com

Como puedes ver, la URL ha cambiado: ya no estamos enviando XML vía POST a un recurso ‘submit’ arbitrario, en cambio estamos llamando un recurso ‘miembros’ que tienen un significado usando el método HTTP GET y especificando parámetros significativos directamente a la URL.

[Dejaré de traducir el código, a fin de acelerar el proceso de traducción.]

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

<?xml version="1.0" encoding="UTF-8"?>
  <data>
    <name>Anna</name>
    <name>Lisa</name>
  </data>

El formato de respuesta no necesita cambiar: como hemos estado viendo, REST no define un formato XML, pero da los principios generales de la arquitectura del diseño.

En cuanto a programación, hay un pequeño cambio en el script utilizando el servicio web (seguimos usando PHP, cURL y SimpleXML). Así es como se vería:

<?php

  // PASO 1: ENVIAR LA SOLICITUD
  $url = 'http://api.community.com/members?age=23&city=Indianapolis';
  $handle = curl_init();
  curl_setopt($handle, CURLOPT_URL, $url);
  curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
  $response = curl_exec($handle);
  curl_close($handle);

  // PASO 2: INTERPRETAR EL RESULTADO Y MOSTRAR LOS NOMBRES.
  if ($response) {
    $result = new SimpleXMLElement($response);
    $val = array();
    foreach ($result->name as $name) {
      $val[] = (string) $name;
    }
    print_r($values);
  } else {
      echo “An error occurred.”;
  }

?>

Nota: en caso de que los parámetros que ingreses a la URL tengan caracteres especiales, necesitas usar urlencode( ) sobre ellos. Tambien hay que notar que añadimos una condicion para verificar la respuesta antes de hacer el bucle sobre ella.

Ahora veamos el script que provee el servicio web; aquí hay un ejemplo de cómo se manejaría la llamada REST (asumiendo que el nombre del script es members.php, localizado en /scripts y accesible a través de una reescritura de URL con apache (mod-rewrite):

RewriteEngine on
RewriteRule ^members(.*)$ scripts/members.php$1

y ahora el script:

<?php

  $connection = mysql_connect('host', 'user', 'password');
  mysql_select_db('database', $connection);

  $age = $_GET['age'];
  $city = $_GET['city'];
  if (!is_int($age) || !is_string($city)) {
    header(’HTTP/1.1 400 Bad Request’);
    exit();
  } else {
    $query = ‘SELECT name FROM members WHERE age=’ . $age .
             ‘ AND city=’ . $city;
    $data = mysql_query($query);
    $members = array();
    header(’Content-Type: application/text-xml’);
    echo “<data>”;
    while ($item = mysql_fetch_array($data)) {
      echo “<name>” . $item['name'] . </name>;
    }
    echo “</data>”;
  }

?>

En pocas palabras, éstas son las razones por las que este nuevo script es más al estilo REST:

• utilizamos el servicio a través de un parámetro GET llamando recursos significativos como members y especificando parámetros significativos en la URI de consulta.
• en caso de que ocurra un error (por ejemplo, datos incorrectos en el parámetro age), usamos un estado dedicado HTTP para enviar el mensaje, en lugar de agregar una capa XML en la respuesta.

Lo más importante sobre REST es que no es sólo un conjunto de recomendaciones de arquitectura. En el siguiente post, echaremos un vistazo a otro estándar de API que se enfoca en el formato del XML más que en la arquitectura en general: XML-RPC.

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á…

Digamos que necesitas subir una colección de 100 fotos en Flickr diariamente. No es tan difícil: inicias sesión en tu cuenta de Flickr y comienzas a subir manualmente las fotos. Sin embargo, después de algunos días, comienzas a sentirte un poco raro al tener que gastar todo ese tiempo subiendo los archivos manualmente  en la era en que las computadoras, después de todo, se supone que nos reemplazan para tareas repetitivas. Digamos que tus colecciones diarias de 100 archivos ya están listas desde un principio: ¿No sería genial si tu computadora pudiera subirlas a Flickr por sí sola?

Parte 1: La manera sucia

Lo primero que viene a la mente es: ¡hagamos que mi computadora llene los formularios sola! La idea es muy sencilla: escribes un script capaz de iniciar sesión en tu cuenta de Flickr usando tus datos y, una vez ahí, llenar los campos del formulario. ¿Llenar los campos del formulario? Eso significa que veré mi computadora en acción y el cursor moviéndose de un campo a otro, abriéndo el diálogo de selección de archivo, haciendo doble click en un archivo, moviendose al siguiente campo, etc.? Bien, no realmente, porque todo esto son cosas por parte del cliente.

En un formulario, sólo tres cosas importan: el método (común mente GET o POST), los nombres de los campos y la URL del action (por ejemplo, la URL a la que tu navegador envía la solicitud cuando presionas el botón de “enviar”).  Al final del día, “llenar automáticamente un formulario” simplemente significa enviar una solicitud GET o POST a la URL con los nombres y valores de los campos correctos.

Comencemos con un caso simple de estudio. Al llenar un formulario GET en el sitio http://www.comunidad.com (ejemplo ficticio), esto es lo que Juan, de 23 años que vive en Guadalajara enviaría al servidor:

GET /submit.php?nombre=juan&ciudad=guadalajara&edad=23 HTTP/1.1
Host: www.comunidad.com

En caso de que el formulario fuera POST, Esto es lo que Juan hubiera enviado:

POST /submit.php HTTP/1.1
Host: www.comunidad.com
Content-Length: 38
Content-Type: application/x-www-form-urlencoded

nombre=juan&ciudad=guadalajara&edad=23

Nota: las solicitudes anteriores son simplificada, conteniendo sólo los encabezados requeridos para los métodos GET y POST, de hecho, muchos encabezados más son enviados comunmente junto con éstos (ve la lista de encabezados HTTP en Wikipedia [en]).

Eso fue genial. Ahora la parte divertida es: al recibir una consulta, los servidores buscan en la base de datos para encontrar otras personas de 23 años que vivan en Guadalajara y envían una página web a Juan con la lista de nombres en ella. Después de que Juan envió su información personal, él verá una página web con los miembros Ana y Lisa.

HTTP/1.1 200 OK
Date: Tue, 10 Jun 2008 19:38:07 GMT
Content-Length: 271
Content-Type: text/html

<html>
   <head>
      <title>Comunidad.com rocks!</title>
   </head>
   <body>
      <h1>Existen 2 miembros de 23 años que viven en tu ciudad:</h1>
      <ul>
         <li>Miembro #1: Anna</li>
         <li>Miembro #2: Lisa</li>
      </ul>
   </body>
</html>

Nota: la página web anterior es una simplificada. ¡Vamos, ni siquiera tiene la declaración DOCTYPE  !

Eso fue tan genial. Llenando un formulario simple, Juan fue capaz de conocer algunos de sus vecinos que también pertenecen a http://www.comunidad.com. En otras palabras: enviando una solicitud, Juan recibió una respuesta con datos en ella. Un humano (suponiendo que no es geek) leería los datos desplegados en su navegador, pero un script puede interpretar el código HTML y extraer los trozos de información relevante.

Ahora Juan es un tipo listo que sabe de computadoras, así que decide escribir un script explotando este formulario y enfocado a obtener los miembros de http://www.comunidad.com de 23 años que viven en Guadalajara. El script esencialmente consistiría en emular el formulario web enviando una solicitud a http://www.comunidad.com y luego interpretando el código HTML resultante. Dicho script fácilmente podría ser usado para saber cuando nuevos usuarios de la misma edad y que viven en la misma ciudad se vuelven miembros en http://www.comunidad.com: para hacer esto, Juan debe ejecutarlo diariamente o hacer una tarea CRON diaria.

Juan sabe PHP y usará una función llamada cURL para escribir las solicitudes y luego una regex (expresión regular) para interpretar el resultado. Así es como se vería el script:

<?php

   // PASO 1: ENVIAR LA SOLICITUD POST
   $url = 'http://www.comunidad.com/submit.php';
   $handle = curl_init();
   curl_setopt($handle, CURLOPT_URL, $url);
   curl_setopt($handle, CURLOPT_POST, 1);
   curl_setopt($handle, CURLOPT_POSTFIELDS,
               'nombre=juan&ciudad=guadalajara&edad=23');
   curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
   $result = curl_exec($handle);
   curl_close($handle);

   // STEP 2: INTERPRETAR EL RESULTADO E IMPRIMIR LOS NOMBRES
   preg_match_all("|<li>Miembro #[0-9]+: (.*)</li>|”, $result, $match);
   print_r($match);

?>

Nota: es más seguro usar más opciones cuando se escribe una solicitud cURL (especialmente opciones como CURLOPT_TIMEOUT).

En este script, Juan decidió simplemente usar print_r() en el arreglo de nombre, pero pudo haber decidido también insertarlos en una base de datos o enviarlos por correo. Lo importante es que: Juan pudo obtener datos estructurados a partir de una consulta usando variables.

El siguiente paso sería extender este script para todas las edades y ciudades en México. Usando dos ciclos anidados conteniendo todas las edades de 21 a 100 años y todas las ciudades principales de México, por ejemplo, sería posible reconstruír una buena parte de la base de datos de los miembros de http://www.comunidad.com.

De hecho, el script que Juan está escribiendo va más allá del uso normal del formulario inicial y ciertamente no está soportado por los propietarios del sitio. Debido a que ellos no quieren que este tipo de scripts exploten el formulario automáticamente y escupa los nombres de los miembros, los desarrolladores de http://www.comunidad.com tienen algunas armas a su disposición:

1. Lo primero que pueden hacer es cambiar regularmente los nombre de los campos, lo que significa que Juan tendría que actualizar su propio script cada vez que se hace ese cambio o de lo contrario el script seguiría enviando ciegamente variables antiguas al servidor.
2. Otra cosa que pueden hacer es actualizar regularmente el código HTML de la página web entregada: por ejemplo, añadiendo una clase a las lineas, rompería la expresión regular.
3. El tercer movimiento; limitar el número de solicitudes en un marco de tiempo determinado, por ejemplo, haciendo imposible que una sola dirección IP envíe más de 1 solicitud cada 10 minutos.
4. Arma letal: añadiendo un captcha, que es un obstáculo mucho más complicado de superar.

El script que juan escribió es una API de la base de datos de http://www.comunidad.com hecha para uso personal del hacker: es un puente hacia el contenido almacenado ahí. Ahora, ¿no sería mejor si, en lugar de estar husmeando nombres de variables y actualizando una expresión regular, fuera posible enviar una consulta estructurada a http://www.comunidad.com y obtener una respuesta estructurada oficialmente soportada y constante?

(Traducido por Nokrosis, basado en el trabajo original de NEMETRAL)

Continuará…