El API de Evernote
Evernote no es un simple cuaderno de notas, también permite clasificarlas y compartirlas. Guarda texto, fotos y audio para que esté disponible en la nube desde cualquier dispositivo. Hoy en día cuenta con versión gratuita y versión Premium (5$/mes, 45$/año). A principios de 2014, Phil Libin, CEO de Evernote, cifraba en 80 Millones el número de usuarios globales. En continuo dinamismo, el mismo Phil aseguraba recientemente que apostarán fuerte por los dispositivos ‘wearable‘.
Parece por tanto una aplicación muy a tener en cuenta. Por ello, vamos a ver una visión general de la API de Evernote.
Introducción al API de Evernote: ¿Qué se puede hacer?
La API está disponible para todas las plataformas importantes, como por ejemplo Python, PHP, Java, OS X, iOS, Android…
Además está bien documentada, ya que cuenta con:
- SDKs para numerosas plataformas, incluso algunas de ellas contienen un breve tutorial ‘quick-start’ para configurarla
- Artículos explicativos de determinadas funciones, operaciones…
- API Reference con todas las declaraciones (también disponible para iOS y Android)
- Foro para desarrolladores bastante activo, donde los propios desarrolladores de Evernote participan en los hilos de preguntas y resuelven los problemas.
Para un primer acercamiento, es necesario apuntar que la API de Evernote es algo peculiar. ¿Por qué? Por la Sandbox. ¿Y eso qué es?
La Sandbox de Evernote
La Sandbox es una instancia separada de Evernote para probar y experimentar con la API. Misma interfaz, mismo funcionamiento, mismo email, pero diferente cuenta de usuario (diferentes cuadernos, notas…). Su principal función es evitar errores en tu cuenta personal o en su plataforma de producción. En resumen, Evernote no quiere que toques tu cuenta principal hasta que no estés seguro de lo que haces, y para lo que será necesario enviar una petición de activación como veremos más adelante.
The most likely way for the world to be destroyed, most experts agree, is by accident. That’s where we come in; we’re computer professionals. We cause accidents. — Nathaniel Borenstein
Por eso hace falta una sandbox…
Primer dan: Autenticación con el API de Evernote
Como la mayoría de las APIs hoy en día, la autenticación se hace mediante OAuth. Si has trabajado con este protocolo en alguna otra aplicación, no hace falta decir que es bastante peculiar. Sin embargo, en este artículo sólo veremos brevemente el funcionamiento básico.
Por tanto, el primer paso consiste en crear la cuenta en la Sandbox y solicitar la API KEY, para lo que nos pedirán tanto el nombre de usuario de Evernote como el de desarrollador (Sandbox). Hay que tener en cuenta que el usuario debe ser diferente del de la cuenta de Evernote principal.
Después de un ir y venir interminable de URLs, como se muestra en la figura, conseguiremos nuestro deseado token, que será una especie de llave mágica que deberemos usar cada vez que queramos hacer una llamada a la API. Se puede ver una guía más detallada en el siguiente enlace: Guía de autenticación completa.
Nota.- Se puede sustituir el proceso anterior de OAuth, instalando el SDK correspondiente desde su perfil de Github y siguiendo las instrucciones que se indican (Por ejemplo, el SDK-python).
Segundo dan: Visión general de la interfaz del API
Sabemos que Evernote tiene tres elementos fundamentales: los cuadernos, las notas y las etiquetas. Cada uno de estos elementos se identifica con su respectivo guid. Siempre que queramos operar con alguno de ellos, deberemos pasar como parámetro este identificador.
Para interactuar debemos iniciar una conexión, que en la documentación se conoce como client y para la que será necesario el token obtenido mediante OAuth.
dev_token = "oauth_result_token" client = EvernoteClient(token=dev_token)
Todos los datos que se pueden manejar en Evernote se encuentran en la NoteStore, y desde ahí será de donde sacaremos las notas o los cuadernos para operar con ellos.
noteStore = client.get_note_store()
notebooks = noteStore.listNotebooks()
for n in notebooks:
print n.name
También existe la UserStore, que nos proporciona información acerca del usuario.
userStore = client.get_user_store() user = userStore.getUser()
Tercera parte: Algunos ejemplos, de menor a mayor dificultad
1) Crear un cuaderno de Evernote:
# Autenticación dev_token = "oauth_result_token" client = EvernoteClient(token=dev_token) # Llamada a la NoteStore noteStore = client.get_note_store() # Creamos el cuaderno notebook = Types.Notebook() notebook.name = "Mi cuaderno molón" # Lo guardamos e imprimimos su identificador notebook = noteStore.createNotebook(notebook) print notebook.guid
2) Filtrar las notas que contengan la palabra ‘STAR WARS’ y que además contengan una fuente URL:
dev_token = "oauth_result_token"
client = EvernoteClient(token=dev_token)
noteStore = client.get_note_store()
# Filtramos las notas con la palabra STAR WARS
updated_filter = NoteFilter(words='STAR WARS')
offset = 0
max_notes = 1000
result_spec = NotesMetadataResultSpec(includeTitle=True)
result_list = noteStore.findNotesMetadata(authToken, updated_filter, offset, max_notes, result_spec)
for note in result_list.notes:
# Localizo la nota con el identificador
noteGuid = note.guid
# note_object es el objeto nota
note_object = client.get_note_store().getNote(noteGuid,False,False,False,False)
url = note_object.attributes.sourceURL
# Si existe la url o no
if url!=None:
print note.title
else:
print "La nota no tiene URL"
Este último ejemplo es bastante interesante ya que se puede ver que para las notas hay dos tipos de instancias digamos: el metadata y el objeto en si. El metadata corresponde con la variable note y consta del título y el contenido de la nota, básicamente. Sin embargo, el objeto nota, en nuestro caso la variable note_object, es que la que tiene los atributos que estamos buscando: la fuente URL. Otros atributos interesantes son las etiquetas, la localización, el autor, el tamaño en Bytes de la nota, las fechas de creación y última modificación…
Por ejemplo, snippet para añadir un tag a una nota:
noteGuid = note.guid
note_object = client.get_note_store().getNote(noteGuid,False,False,False,False)
# Tenemos identificado el tag 'SKYWALKER' con su guid
# 3012f008-8af4-4ff6-a2a4-6487836e7b23 tag guid --> SKYWALKER
if '3012f008-8af4-4ff6-a2a4-6487836e7b23' in note_object.tagGuids:
print "Ya existe el tag"
else:
# Añadimos el tag
note_object.tagGuids.append('3012f008-8af4-4ff6-a2a4-6487836e7b23')
# Actualizamos la nota en la NoteStore
noteStore.updateNote(dev_token, note_object)
# Imprimimos los tags de la nota
print note_object.tagGuids
Se debe comentar que los tags de una nota en Evernote se comportan como una cadena de strings, formada por los identificadores de los tags. Por tanto, para añadir, borrar o editar cualquier tag, debemos acudir a la lista de note_object.tagGuids y hacer la operación necesaria con el correspondiente guid.
3) Obtener las notas de un cuaderno que han compartido con tu cuenta
Esto es realmente útil cuando se comparten libretas entre varios usuarios. La NoteStore solamente almacena los datos propios de cada usuario. Sin embargo, si alguien ha compartido un cuaderno con nosotros y queremos sacar las notas que tiene. ¿De dónde las sacamos?
authToken = "evernote_account_token"
client = EvernoteClient(token=authToken, sandbox=False)
noteStore = client.get_note_store()
# Obtenemos todos los cuadernos que han compartido con nosotros
linked_notebooks = noteStore.listLinkedNotebooks(authToken)
# Cogemos el primero de ellos, por defecto
linked_notebook = linked_notebooks[0]
# shareKey para el cuaderno
shareKey = linked_notebook.shareKey
# Sacamos la note store compartida!!!!
note_store_uri = linked_notebook.noteStoreUrl
shared_note_store = Store(authToken, NoteStore.Client, note_store_uri)
# Nos autenticamos en el cuaderno compartido gracias al shareKey y al authToken
auth_result = shared_note_store.authenticateToSharedNotebook(shareKey,authToken)
# Obtenemos el share_token
share_token = auth_result.authenticationToken
# Filtramos todas las notas
updated_filter = NoteFilter(words=' ')
offset = 0
max_notes = 40000
result_spec = NotesMetadataResultSpec(includeTitle=True)
# Notar que ahora las sacamos de shared_note_store con su correspondiente token
result_list = shared_note_store.findNotesMetadata(share_token, updated_filter, offset, max_notes, result_spec)
for note in result_list.notes:
#Identificamos cada nota
noteGuid = note.guid
#Volvemos a sacar las notas de la shared_note_store en vez de la NoteStore
note_object = shared_note_store.getNote(share_token,noteGuid,False,False,False,False)
# Imprimimos sus atributos
print note_object.attributes
Este ejemplo, como es fácilmente apreciar, es más complicado que los anteriores. En primer lugar, la principal diferencia es que los cuadernos compartidos sólo están disponibles en las cuentas principales de Evernote y no en la Sandbox. Por lo tanto, para poder trabajar con ellos, debemos haber activado nuestra API KEY rellenando el formulario ‘Activate an API KEY‘ y al obtener el client en la autenticación pasarle el parámetro sandbox=False. Como vemos, debemos autenticarnos dos veces, para el client con el auth_token y para la shared_note_store con el share_token (para el que nos hace falta la share_key). Obviamente, nuestras operaciones en un cuaderno compartido están sujetas a los permisos que el propietario nos haya otorgado.
¡Ya eres un padawan del API de Evernote!
Como resumen final, hemos visto una visión global de la API de Evernote con varios ejemplos prácticos de diferente dificultad. Hemos intentado trabajar con todos los elementos (cuadernos, notas y etiquetas), y también hemos visto un ejemplo de uso fuera de la sandbox en el que al acceder a un cuaderno compartido debemos autenticarnos doblemente.
Por tanto, hemos realizado un análisis completo de la API para saber lo necesario para afrontar exitosamente la interacción con Evernote.
¿Te animas a hacer algún plugin? ¡Hay todo un mercado y Evernote organiza conferencias, eventos y premios! Y si quieres más, mira nuestros bootcamps de programación y tecnología.
