11870.com API 101 (con Python): autenticación

septiembre 1st, 2009 api peralta

Si bien tenemos la documentación de nuestra API bastante limpia y al día, algo de certeza hay en eso de que tiene una curva de aprendizaje un tanto pronunciada dependiendo de lo que queramos hacer. En este primer post vamos a dar una vuelta rápida por alguna de las funcionalidades que se ofrecen usando el lenguaje de programación Python (con las librerías httplib2 y feedparser), aunque en realidad lo que aquí se explica es fácilmente portable a otros lenguajes de programación.

Esta entrada forma parte de una serie (11870.com API uanou uan) que intenta dar una visión más práctica de nuestra API. La documentación relevante a seguir es API authentication.

Obteniendo una API key

Lo primero que querremos hacer será generar una nueva API key. Para ello nos vamos a 11870.com/usuario/apps/new con nuestro navegador y rellenamos el formulario (importante la sección de notas, que nos gusta saber para qué se nos utiliza). Como resultado obtendremos dos cosas:

• una clave de aplicación (API key) o appToken
• un secreto asociado a esa clave de aplicación

Tenemos dos formas de autenticar nuestras peticiones dependiendo de si sólo vamos a usar sólo las funcionalidades de búsqueda o todas.

Las peticiones de búsqueda requieren que se añadan dos parámetros adicionales para ser autenticadas: appToken y authSign. Los valores de estos parámetros son estáticos (cosa que cambiará en una futura revisión de la API) y en el caso del appToken es la misma clave de aplicación obtenida anteriormente mientras que authSign es un hash que se calcula haciendo el md5 de la clave de aplicación seguido del secreto concatenado. Para calcularlo:

>>> from hashlib import md5
>>> md5(appToken + secret).hexdigest()
'f688ae26e9cfa3ba6235477831d5122e'
>>>

Si preferimos hacerlo en shell:

$ echo -n ${APPTOKEN}${SECRET}|md5sum
f688ae26e9cfa3ba6235477831d5122e  -
$

Con esto ya podemos lanzar la primera query de búsqueda:

>>> import httplib2
>>> h = httplib2.Http()
>>> request, content = h.request("http://11870.com/api/v1/search?q=mudanzas&appToken=" + appToken + "&authSign=" + authSign)

Con las consultas de búsqueda, es muy cómodo trabajar con feedparser, que trata nuestras respuestas perfectamente:

>>> import feedparser
>>> feed = feedparser.parse(content)

A partir de ahora, la navegación del objeto feed es coser y cantar. Por otro lado, si nos sigue gustando el shell, hay para todos los gustos:

$ curl "http://11870.com/api/v1/search?q=mudanzas&appToken=${APPTOKEN}&authSign=${AUTHSIGN}"

En cuyo caso obtendremos el XML de resultado a pelo.

Hasta aquí digamos que nuestra API no ha mostrado lo áspera que puede llegar a ser (eso sí, sólo las primeras veces ;). Como pronto vamos a empezar a realizar ya peticiones de manejo de agenda, necesitaremos autorizar a nuestra aplicación para que la gestione. Para hacerlo a mano tenemos que ir a la siguiente URL:

http://11870.com/manage-api/create-token?appToken=APPTOKEN&authSign=AUTHSIGN&privilege=WRITE&returnUrl=http://www.google.es”

estando ya autenticados en 11870.com. Veremos que se nos solicita conceder autorización a la aplicación para manejar nuestros sitios (y también contactos e información de perfil). Al hacerlo, nos iremos a una página de resultados de google y de ahí tendremos que coger el authToken.

Esto último suena un poco raro, lo que ocurre por debajo es que 11870.com redirige a la URL que hayamos puesto en en el parámetro returnUrl añadiendo un parámetro adicional que es authToken con el valor que nos interesa. Este parámetro es parecido a una contraseña, ya que está vinculada a nuestro usuario y aplicación.

A partir de ahora podremos autenticar las peticiones que hagamos usando el esquema de autenticación WSSE. Como usuario utilizaremos el email del usuario y como contraseña el authToken que acabamos de obtener:

>>> h.add_credentials("luis@11870.com", authToken)
>>> request, content = h.request("http://11870.com/api/v1/search?q=bares")
>>>

Conclusiones

Tres cosas deberían quedar claras después de leer este artículo:

• cómo generamos una nueva clave de aplicación y somos capaces de obtener el valor de authSign
• que hay dos formas de realizar peticiones contra la API: o añadiendo parámetros a la query (si sólo usamos la búsqueda) o usando WSSE (si queremos poder gestionar datos del usuario)
• cómo autorizar a nuestra aplicación para que acceda a la agenda de un usuario

En próximos capítulos de la serie (dejadme que lo vuelva a decir: 11870.com API uanou uan) veremos cómo gestionar la agenda de un usuario, sus contactos, sus datos de perfil y acceder a su actividad social.

Tags: api, atompub, feedparser, httplib2, python, wsse

3 comentarios

Comments RSS TrackBack Identifier URI

Deja un comentario