Introducción

Notion es una gran herramienta y esencial para mí. Es como un segundo cerebro. Sin embargo, una vez entendidos los conceptos básicos, se puede sacar aún más partido. Hay muchas tareas repetitivas que, a pesar de lo usable que es la plataforma, se pueden acortar o incluso automatizar. Afortunadamente, cuenta con una API pública y muy funcional que le da un impulso extra a la plataforma.

En mi camino para entender el API, a pesar de contar con un wrapper bastante cómodo, me topé con una curva que, aunque no es pronunciada, puede considerarse incómoda. Este tutorial es para todos aquellos que quieran convertirse en usuarios avanzados de la plataforma y aprovechar sus habilidades de programación.

Configuracion del API

Asumire que ya poseen una cuenta de Notion. Para comenzar a desarrollar una integracion, lo primero sera obtener un token de acceso en la siguiente pagina

En el apartado de "Nueva Integración", introduciremos los datos de la integración (nombre, foto, workspace, etc). Quiero hacer hincapié en una opción aquí, y es la de los permisos. A la hora de otorgar estos permisos, deben tener claro el propósito de la integración, ya que otorgar permisos innecesarios puede conllevar a una pérdida de información sensible si el token acaba en manos incorrectas.

Una vez obtenido el token, podemos empezar a desarrollar. La elección del lenguaje fue Python debido a su sencillez y facilidad de uso. Además, también es uno de mis lenguajes preferidos. Esto nos permite comenzar a trabajar de forma rápida y eficaz. Para abstraer el trabajo con la API usaremos una librería llamada notion-client.

Manos a la obra!

Primero, instalemos la librería con pip install notion-client y la importamos en el archivo como notion_client. Luego, creamos un archivo .env que nos servirá para guardar el token de integración y algunas otras variables útiles. También recomiendo instalar e importar la librería dotenv para importar las variables de entorno.

Para indicar con qué cuenta de Notion en específico queremos trabajar, instanciamos la clase Client y le pasamos como argumento el token de integración anterior.

import notion_client
import dotenv
import os

dotenv.load() #Carga el archivo .env

notion = notion_client.Client(auth=os.getenv(<Nombre_de_la_variable>)

Esta clase Client tiene una serie de atributos (pages, search, databases, blocks…) sobre los cuales vamos a ejecutar métodos. El primer ejemplo será sencillo, haremos una búsqueda por nombre de una base de datos.

Creamos una página cualquiera en Notion y dentro insertamos una base de datos con el nombre "Media-Center". Es importante tener en cuenta que, para que la integración tenga acceso a una página y a sus páginas hijas, debemos otorgarle permisos expresamente. Esta es una medida de seguridad adicional muy acertada.

A continuación haremos algo simple. Una búsqueda dentro de las páginas a las que tiene acceso la integración.

def retrieve_db_id(db_name):
		"""
		El metodo search admite como argumentos tipo key-value queries, filtros,
		cursores y algunos mas para hacer las busquedas mas precisas. Mas informacion 
		en: <https://developers.notion.com/reference/post-search>
		"""
    search_database = notion.search(
        query=f"{db_name}",
        property='object',
        value='database'
    )

Es bastante intuitivo todo. Este método hará una petición al endpoint correspondiente, y devolverá un JSON con un formato similar al siguiente:

[
  {
    "object": "database",
    "id": "33df8e82-44c2-4b56-aa71-f9e741ce6036",
    "cover": "None",
    "icon": "None",
    "created_time": "2023-01-09T00:13:00.000Z",
    "created_by": {
      "object": "user",
      "id": "73f136ee-80e3-40ca-bee7-8edd495910a5"
    },
    "last_edited_by": {
      "object": "user",
      "id": "73f136ee-80e3-40ca-bee7-8edd495910a5"
    },
    "last_edited_time": "2023-01-09T00:33:00.000Z",
    "title": [
      {
        "type": "text",
        "text": {
          "content": "Media-Center",
          "link": "None"
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Media-Center",
        "href": "None"
      }
    ],
    "description": [],
    "is_inline": true,
    "properties": {
      "Tags": {
        "id": "LtkD",
        "name": "Tags",
        "type": "multi_select",
        "multi_select": {
          "options": []
        }
      },
      "Name": {
        "id": "title",
        "name": "Name",
        "type": "title",
        "title": {}
      }
    },
    "parent": {
      "type": "page_id",
      "page_id": "fe7a9d3f-2991-424f-8b48-3f05cfe08bd0"
    },
    "url": "<https://www.notion.so/33df8e8244c24b56aa71f9e741ce6036>",
    "archived": false
  }
]

Dependiendo de la cantidad de bases de datos y sus características, este JSON tomará una forma diferente, pero se darán cuenta de que sigue un patrón entendible. Por ahora, solo nos devolvió un resultado y de aquí extraeremos la segunda propiedad llamada id con la cual trabajaremos a partir de ahora. Esta también se encuentra en la URL de la página con el siguiente formato https://www.notion.so/{workspace_name}/{database_id}?v={view_id}.

Una vez tengamos el id de la base de datos, podemos obtener directamente los metadatos de la base de datos de la siguiente manera:

def retrieve_db(id):
    database = notion.databases.retrieve(database_id=id)
    return database

Ojo: este método no devuelve el contenido, sino información similar a la búsqueda del principio, pero solamente de la base de datos seleccionada. Para obtener la información dentro, usamos el método query :

def retrieve_db_content(id):
    database = notion.databases.query(database_id=id)
    return database

Ahora vamos con algo más útil. Manipular bases de datos. Una base de datos está compuesta por páginas, y estas a su vez contienen una serie de elementos dentro que nos interesa manipular. Vamos a insertar los siguientes campos en nuestra base de datos para simular un caso real:

• Name (title)
• Image (files)
• Summary (rich_text)
• Genre (multiple_select)
• Year (date)
• URL (url)

Para crear una página (fila) en esta base de datos, usamos el siguiente método:

def insert_page(database_id, properties):

    notion_page = notion.pages.create(
        parent={'database_id': database_id},
        properties=properties)

	return notion_page

El argumento database_id se refiere al id de la base de datos a la cual pertenece la página, y el cual aprendimos a extraer al principio. El otro argumento properties se refiere a un diccionario que contiene la información de las propiedades de la base de datos.

Cada propiedad de una base de datos de Notion tiene características particulares. Al final del artículo voy a dejar un enlace donde aparecen todas y sus requerimientos. El diccionario toma la siguiente forma:

properties = {
    'Name': {'title': [{'text': {'content': <title_name>}}]},
    'Image': {'files': [{'name': <image_name>, 'external': {'url': <image_url>}}]},
    'Summary': {'rich_text': [{'text': {'content': <summary_text>}}]},
    'Genre': {'multi_select': [{'name': <genre_name>}, {'name': <genre_name>}]},
    'Year': {'date': {'start': f'{datetime.datetime.now().isoformat()}'}},
    "URL": {"url": <url>}
}

Cada campo sigue un patrón parecido en principio.

<Property_name> : {<property_type> : <specific_data>}

Sin embargo, cada propiedad tiene particularidades. Por ejemplo:

La primera tiene el nombre de title. Toda página tiene esa propiedad y es obligatoria.

La propiedad de archivos files puede ser tipo file (hosteado por Notion) oexternal(hosteado externamente), aunque de momento solo se puede insertar mediante llamadas la API enlaces externos. Es obligatorio un nombre alternativo para el archivo.

Summary es rich_text, lo que significa que puede tener colores, estilos y mucho más. Sin embargo, solamente pasamos texto plano en esta ocasión.

Genre es de tipo multiple_select, lo cual significa que dentro contiene una lista de diccionarios, que a su vez dentro estan formado por la llave name y su valor correspondiente.

Las fechas en Notion se manejan de acorde al formato ISO 8601, por lo que en el caso de Year usamos la libreria datetime para formatear la hora adecuadamente. Solo use la fecha de inicio para representar un dia, pero existe la opcion de fecha final.

La url es bastante sencilla. Simplemente le pasas la url y listo.

En la documentación los campos para insertar una propiedad pueden aparecer con el siguiente formato:

<Property_name> : {'type': <property_type>, <property_type> : <specific_data>}

Pero realmente no es necesario, incluso, llega a ser redundante.

Vamos a probar si funciona con datos de prueba:

A partir de este punto ya se tiene el contexto suficiente para empezar a consumir la API y, junto a la documentación, empezar a hacer cosas increíbles con Notion: desde manejar finanzas personales, llevar seguimiento de hábitos, notas, planes de entrenamiento, almacenamiento de información, etc… ¡La imaginación es el límite!

Espero que les haya servido. Cualquier duda pueden pasar por mi canal y grupo de Telegram y estaré encantado de ayudarlos.

Enlace útiles

Página principal de notion - https://notion.so

Documentación - https://developers.notion.com

Lista de propiedades de una pagina - https://developers.notion.com/reference/page-property-values

Github de la librería - https://github.com/ramnes/notion-sdk-py

Para registar el dominio usaremos Freenom (ojo, usen vpn. Yo a diario uso y recomiendo este). Por alguna razón, Freenom tiene defectos técnicos a la hora de registrarnos, se darán cuenta si lo intentan, aunque eso solo afecta al flujo de registro (no vamos a aprovecharnos de ningun bug para obtener el dominio, son gratis por defecto).

Luego, buscamos si el dominio esta disponible y nos saldran las extensiones gratuitas disponibles. Divisamos la que más nos guste y en vez de presionar "Consígalo ahora"(ahi hay otro error de los que hablé antes), volvemos a escribir el dominio en la barra de busqueda pero con la extensión ya incluida:

Presionemos en finalizar compra y en la proxima vista seleccionamos 12 meses gratis.

Se nos pedirá un correo electronico que es el que usaremos para registrarnos en la plataforma y al que nos mandaran un código de verificación.

Evidentemente, al tener que usar vpn podemos intuir que el sitio cuando huele Cuba ahi mismo empiezan los "fallos" (lo comprobé, no se puede poner la información real de un cubano), aunque eso es facilmente sorteable ya que al no manejar dinero no necesita mucha comprobación. Esto tiene sus pros y sus contras. Pro: Con páginas como https://www.fakepersongenerator.com/ rellenamos los campos y aquí no pasó nada. Contra: lo primero que dije en este tutorial, esto no tiene respaldo legal y no deberia usarse para un negocio ni nada importante.

Luego de eso todo estaría en orden, y ya tendríamos el dominio en nuestra cuenta :)

Solo resta iniciar sesión con el correo y contraseña en la página de inicio(ahora si funciona) y listo!. Ya podemos empezar a administrar nuestros dominios.

Este tutorial se centra en adquirir un dominio con fines educativos y de pruebas, sin embargo, y sin desprestigiar a Freenom, recomiendo adquirir uno de pago propio en sitios como Godaddy o Namecheap (donde incluso, aceptan criptomonedas y se hace mas accesible para un cubano). Ojalá les haya servido, un saludo.

Hay algo que hago a diario y quisiera recomendárselo a todos: Lean. Un amigo hace poco me comentó una frase la cual, por cierto, me encantó, que reza: "Somos lo que leemos".

Me he dado cuenta que cada dia se va haciendo mas dificil hablar con la gente de temas variados, con algo más de profundidad que solo alcanza el que ve mas allá de titulares de articulos de redes sociales y reality shows. Siempre se termina en los mismos temas, en las mismas opiniones sin pensamiento critico, sin cuestionamiento de la realidad. Tal parece que es una masa pensante compacta a la cual se le prohíbe hablar de ciertos temas y pensar de manera diferente.

En mi caso personal, debo admitir que en algun momento toqué ese fondo. Seamos sinceros: ¿Quién no? Cuando terminé el preuniversitario tuve una epifanía. Ví que aun tenía 18 años, que tenía muchos libros y, sin embargo, si había leído más de 2 era mucho. Gracias doy de haberme dado cuenta temprano. Ahí empezó mi camino con la lectura. Leer me ha permitido expandir mis horizontes. Ha logrado abrirme la mente y, de lo que más me alegro, ha ido aclarándola. Debido a la lectura hoy puedo, siquiera, dar una opinion medianamente basada ámbitos como la política o la religión. Sin embargo, y esto es llamativo, mientras más leo más me paro a pensar: "Cuanto me falta por aprender aun...".

Hoy, más que nunca, es muy fácil acceder a literatura, y muy buena. Audiolibros, libros electrónicos, librerías, etc. En vez de scrollear la red popular de turno, podéis dedicarle una hora al día al menos, como yo, a leer un buen libro. Verán como su salud mental y su cultura mejoran.

Vivo en Cuba. Hasta hace unos años jamás conocí lo que era el copyright, simplemente pensaba que cada cual era libre de utilizar el contenido a su antojo: Después de todo :¿Que daño haría? Las mismas películas que salían en los cines las teníamos en el paquete semanal en cuestión de dias, la música también. Los programas con exorbitantes licencias están al alcance de un crack.

Muchas de estas prácticas están condicionadas por el país, no podemos separar los pies de la tierra. De no ser por el paquete semanal Palmas y Cañas y la Mesa Redonda (programas televisivos cubanos de entretenimiento e informacion política respectivamente) hubieran sido líderes en audiencia durante los numerosos años de censura informativa que han transcurrido. Sin embargo, la piratería comienza a ser un problema cuando tenemos la opción de hacer las cosas bien, y aun así elegimos el mal camino.

Los cubanos de la isla irrumpimos en el internet de manera masiva hace poco, y aun muchos no han logrado comprender las infinitas posibilidades que este representa. Me atrevo a decir que muchas personas tienen el sistema operativo Windows pirata, otros usan apks o programas descargados de sitios de muy baja reputación cuyos nombres en ruso traducidos al español posiblemente sean: "Lleve su ransomware aquí que nos los quitan de las manos". Otros tienen la suerte de emigrar y jamás pagan los pocos dolares que cuestan la suscripción a Spotify o Netflix. Lo llevamos en la sangre.

Hace pocos años yo era de los mas acérrimos defensores de esa filosofia, sin embargo, crecí. Cuando empiezas a entender la importancia del trabajo, de como funciona la sociedad y el justo intercambio de valor entre pares es que ves con otros ojos esas malas costumbres. La clave para comprender todo es darte cuenta que detrás de cada producto hay un creativo, un emprendedor, decenas o cientos de horas de trabajo, tiempo y esfuerzo muy valioso. Esas personas que despectivamente hablan de los precios que ponen las empresas y que viven pirateando a dos manos realmente no se han puesto en el lugar del creador cuando vandalizan su obra.

Hay una alternativa gratis para casi todo. Y para lo que no, una de muy bajo costo. Solo hay que despertar ese sentimiento de conciencia en si mismo. La sensación de pagar por el esfuerzo de alguien y obtener un producto digital legalmente es reconfortante. Hacer las cosas bien debería ser la norma, y no la excepción.

Un saludo a quienes me acompañaron hasta el final, nos leemos en Telegram 😄