Como decía en el artículo anterior, de introducción al API de Pixlr, esta API no está aun muy documentada. Quizás cuando leas este artículo la documentación ya se haya mejorado, pero de momento sirvan estas líneas para dar un breve repaso a lo que nos proporciona esta interfaz de programación.

La documentación publicada sobre el API de Pixlr se puede encontrar en la siguiente URL:

http://www.pixlr.com/api/

Este API realmente es muy sencilla de usar e implementar. No necesita descargar nada, ni solicitar permiso de uso, ni nada similar. Simplemente tendremos que seguir unas instrucciones para generar y procesar URLs con parámetros que servirán para comunicarse entre nuestro sitio web y el servicio online de Pixlr.

Los parámetros indicarán datos como la URL de la imagen que se desea editar, el título, el idioma de la interfaz de Pixlr que preferimos, etc. Así que realmente sólo necesitamos conocer cuáles son estos parámetros y cómo enviarlos a Pixlr o procesarlos cuando el API nos los envíe a nuestro sitio.

Podemos dividir los parámetros en dos grupos, de entrada y de salida. Así es como está explicado en la documentación. Los de entrada sirven para enviar los datos a Pixlr y los de salida sirven para que Pixlr nos envíe datos a nosotros.

Parámetros de entrada (input)

Existen varios parámetros para que nuestro sitio web informe a Pixlr qué imagen deseamos procesar y diversas otras cosas relacionadas.

Es importante que cuando envíes datos a Pixlr los codifiques en formato de URL, lo que puedes conseguir con la función de PHP urlencode().

• loc: con este parámetro le indicamos a Pixlr qué idioma debe mostrar en la interfaz. Por defecto es en inglés, (valor "en"), pero también podemos indicarle que queremos el idioma en español "es".
• referrer: este parámetro sirve para indicar un texto, que se mostrará en la ventana de diálogo para guardar la imagen retocada. El texto puede ser el nombre de tu sitio web. Algo como "Desarrollo Web". Atentos a este parámetro, que si no se utiliza en conjunto con el parámetro target, no se tendrá en cuenta y Pixlr no permitirá guardar la imagen en nuestro servidor.
• exit: este parámetro sirve para indicar una URL a la que queremos que Pixlr redirija al navegador en caso que el usuario cierre la aplicación online con el menú Fichero / Salir.
• image: importante parámetro, con el que indicamos la URL de la imagen que queremos que se abra en Pixlr al iniciar la aplicación online.
• title: con este parámetro indicamos el título que queremos que tenga la imagen, que se visualizará en la ventana de la imagen abierta en Pixlr que vamos a editar.
• method: aquí podemos indicar qué método queremos que Pixlr utilice para devolver los datos de salida. Los valores posibles son POST o GET. En el caso de POST generará los datos de salida y los mandará a nuestro servidor como si los enviara mediante un formulario. En caso de GET, nos enviará los datos a nuestro servidor como parámetros en la URL.
• target: este parámetro nos sirve para indicar a Pixlr la URL de nuestro servidor donde se tienen que enviar los datos de la imagen editada y salvada. Esa URL en principio será página con un script PHP (o el lenguaje de programación de servidor que utilices), que se tiene que encargar de recibir los datos enviados de Pixlr y hacer aquello que necesitemos con la imagen que ha salvado el usuario.
  
• Redirect: Con este parámetro podemos decirle a Pixlr una URL distinta al target, al que redirigir al usuario una vez salvada la imagen. Si se indica, el navegador del usuario se redirigirá a esa página, si no, simplemente se le redirigirá a la URL definida en el parámetro target.

Por entender un poco cómo utilizar esos parámetros, podemos fijarnos en la siguiente URL:

http://www.pixlr.com/editor/?loc=es&image=http%3A%2F%2Fwww.guiarte.com%2Farchivoimg%2Fimagenes-usuarios%2F1841.jpg

Faltan varios parámetros importantes por declarar en la URL, pero podemos ver cómo si entramos allí se abre la página de Pixlr y se muestra directamente una imagen que podríamos editar (cuya URL está indicada en el parámetro "image").

Parámetros de salida (output)

Ahora vamos a ver los parámetros que Pixlr enviará a nuestro sitio web para enviarnos la imagen editada por el usuario. El mecanismo es el siguiente:

Una vez abierta la imagen con Pixlr, el usuario se supone que hará sus retoques y en algún momento la guardará, mediante el menú "Fichero / Guardar". Entonces (si habíamos indicado los parámetros de input "referrer" y "target") propondrá al usuario guardarla dentro de nuestro sitio web. En caso que el usuario la guarde en nuestro sitio web, se generará una llamada a nuestro servidor, a una URL que se encargará de procesar la imagen editada. Esa llamada enviará datos, ya sea por POST o GET, según hayamos configurado el parámetro input "method".

Lo que tenemos que saber es que, los datos que envíe, consistirán en diversos parámetros, que son los llamados parámetros de salida (output). Nuestro sitio web debe recibir esos parámetros y procesarlos para obtener de ellos la imagen editada, así como otras informaciones. Estos son los parámetros de Ouput del API:

• image: es la URL de la imagen editada y salvada por el usuario. Esta URL está dentro del sitio web de Pixlr, pero mediante programación de servidor podemos acceder a ella y copiarla en nuestro servidor.
• type: es el formato del archivo (jpg o png) elegido por el usuario al guardar la imagen.
• state: es el estado de la imagen, que puede ser "new" o "fetched". (no sé muy bien para qué sirve este dato)
• title: es el título que le ha puesto el usuario a la imagen a la hora de guardarla.

Nuestra página PHP, o en el lenguaje de programación que trabajemos, recibirá por GET (o POST si lo preferimos) esos datos para hacer cualesquiera acciones con la imagen, como copiarla al servidor, meterla en base de datos, etc.

En próximos artículos publicaremos los códigos PHP que hemos utilizado y comentado para poner en marcha estas pruebas del API de Pixlr. Pero mientras tanto, también podéis ver unos ejemplos en la propia documentación del API.