Nokrosis

Antes que nada una disculpa por el tiempo , en caso de que alguien haya seguido este blog por estas traducciones, trataré de acelerarlas un poco. Ultimamente he tenido bastante trabajo. Gracias por comprender. Continuemos…

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

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.

Trackback URL