Utiliser Notion comme headless CMS (API)

Qu’est-ce que l’application Notion ?

L’application Notion a été fondée en 2016 à San Francisco par Ivan Zhao et Simon Last.

Il s’agit initialement d’une application de prise de notes qui s’est très rapidement diversifiée. Elle propose aujourd’hui de nombreuses fonctionnalités utiles comme la création de :

• Tableur
• Base de données
• Tableau Kanban
• Agenda
• Diagramme de Gantt
• Espace de stockage
• Wikis
• Etc.

En intégrant toutes ces fonctions, Notion excelle dans la création d’espaces de travail personnalisés.

L’application Notion s’imposera par la suite rapidement sur le segment des logiciels de gestion de projet, en permettant entre autres, le travail collaboratif en temps réel.

Comprendre Notion

Les pages

Aujourd’hui, Notion permet de gérer des contenus au sein de pages. Une page est définie par :

1. Un titre
2. Une image de couverture (facultative)
3. Une icône (facultative)
4. Un contenu se construit en utilisant des « blocs ». Ces blocs permettent d’insérer des titres, des paragraphes, des listes, des médias, des tableaux, des widgets (Google Maps, lecteur YouTube…) et bien d’autres ressources.

Les bases de données

Ce qui rend Notion vraiment modulable, c’est en grande partie sa capacité à classifier ces pages au sein de bases de données. Les pages stockées au sein de bases de données vont ainsi pouvoir partager des caractéristiques communes appelées propriétés.

Avec ces propriétés, il devient ainsi possible de gérer n’importe quel contenu que pourrait utiliser un site web : articles de blog, produits e-commerce, etc.

Utiliser Notion comme CMS

Qu’est-ce qu’un CMS ?

Un CMS (Content Management System) est un logiciel en ligne permettant de créer et administrer les contenus d’une application (site web, application mobile, chatbot…), sans nécessiter de connaissances en développement. Ce type d’outil est souvent désigné par l’expression « outil No Code ».

Notion en tant que CMS

Mais Notion compte bien s’imposer dans le secteur des CMS en orientant peu à peu son développement en ce sens.

Cela se traduit évidemment par le fait de pouvoir l’utiliser directement depuis un navigateur (sans passer par une application desktop ou smartphone) mais surtout par sa fonctionnalité de partage. En haut de chaque page créée avec Notion on peut remarquer l’option Partager. Cela permet :

• D’inviter des personnes sur son espace de travail Notion (= workspace).
• De partager des pages sur le web. Pour cela, on remarque que les pages Notion sont hébergées via le sous-domaine .notion.site. Cette fonctionnalité de partage constitue les prémices de Notion en tant que CMS.

Avec la croissance et la démocratisation de Notion, de nombreuses technologies ont vu le jour autour de l’écosystème Notion. C’est entre autres le cas de super.so, potion.so ou encore simple.ink qui proposent de créer des sites web performants à partir de pages Notion. Ces applications permettent par exemple :

• D’optimiser le SEO (chemins d’URL, title et méta description spécifiques pour une page)
• De customiser les pages avec des thèmes (préconstruits ou customisés)
• D’obtenir de bonnes performances avec la génération de pages statiques

Si de manière générale les CMS facilitent grandement la gestion d’un site web, ils présentent 2 contraintes potentielles :

1. Le fait de dépendre aussi du CMS pour la mise en page du site
2. Sa distribution pour différents canaux (si un même contenu doit pouvoir être distribué à diverses plateformes)

Notion en tant que Headless CMS

Le « head » de « Headless CMS » fait référence au front office. Un système de gestion de contenu headless est alors constitué :

• D’un système pour stocker et gérer le contenu (type CRUD)
• D’une API pour interagir avec le contenu

Cette approche permet aux développeurs de fournir un contenu en tant que service (CaaS).

En séparant la couche de gestion du contenu de la couche de diffusion de ces mêmes contenus, un headless CMS vient ainsi résoudre les 2 problématiques évoquées dans le chapitre précédent : le templating des pages peut être géré par une technologie indépendante (Next, Nuxt…) et les contenus peuvent être exploités depuis de nombreux canaux (applications mobile, sites web…).

Utiliser l’API de Notion

#1 Créer une intégration

Une intégration permet d’interagir par programmation avec des données stockées via Notion. Une intégration est essentielle afin de :

• Connecter Notion à une application tierce
• Automatiser des workflows dans Notion
• Exploiter l’API de Notion

Pour créer une intégration Notion, rendez-vous sur https://www.notion.so/my-integrations, puis cliquer sur le bouton + Nouvelle intégration.

1. Donner un nom à l’intégration
2. Uploader un logo (facultatif)
3. Sélectionner un espace de travail Notion sur lequel installer l’intégration
4. Pour les capacités, laisser les valeurs par défaut
5. Cliquer sur Envoyer pour enregistrer l’intégration

Sur la page suivante, vous verrez apparaître votre « jeton d’intégration » (aussi appelé « clé API »). Ce jeton est confidentiel** et sera **indispensable** lors de vos appels API.

#2 Créer une base de données

1. Se placer dans un workspace Notion
2. Cliquer sur Ajouter une page dans la sidebar
3. Saisir un titre pour votre base de données. Par exemple : « Articles »
4. Cliquer sur Table dans la rubrique Base de données (vous pourriez très bien cliquer sur Gallery, cela n’est que cosmétique)
5. Cliquer sur Nouvelle base de données dans la sidebar secondaire qui s’ouvre sur la droite
6. Créer par exemple les propriétés suivantes : Titre, Slug, Description, Tags, Statut et Date de création
7. Ajouter des enregistrements fictifs dans votre base de données

#3 Partager la base de données avec l’intégration

Nous possédons désormais une intégration Notion ainsi qu’une base de données : faisons leur faire connaissance !

Afin de pouvoir utiliser l’API Notion pour communiquer avec des pages ou des bases de données, ces dernières doivent être partagées à notre intégration.

Pour cela, rendez-vous sur votre base de données préalablement créée et cliquer sur … tout à droite de l’entête.

Survoler + Ajouter des connexions et cliquer sur votre intégration qui devrait apparaître dans la liste. Votre intégration a désormais accès à votre base de données !

#4 Utiliser l’API

Toutes les requêtes que nous enverrons à ‘API de Notion devront contenir les 2 en-têtes HTTP suivantes :

• Authorization : votre clé API
• Notion-Version : la version de l’API Notion. Ce versionnage de l’API permet d’éviter les « breaking changes ». Au moment de la publication de cet article, cette version est définie à 2022-06-28. Ce numéro indique la date de la dernière release au format yyyy-mm-dd.

Ouvrons désormais Postman afin de faire nos premiers tests API.

{
	"object": "list",
	"results": [
		// les pages stockées dans la BDD
	],
	"next_cursor": null,
	"has_more": false,
	"type": "page",
	"page": {}
}

{
	"filter": {
		"property": "Statut",
		"status": {
			"equals": "Publié"
		}
	}
}

Pour effectuer n’importe quel autre type d’appel (récupération du contenu d’une page, ajout d’un enregistrement en base de données… Je vous laisse le soin de consulter la référence de l’API Notion.