API

Memo répond aux programmes comme aux navigateurs. Cette page donne toutes les adresses que le serveur sert, ce qui ouvre chacune, et ce qui revient.

Tout ce que la liste des tableaux et la page d'administration font en HTTP, un programme peut le faire aussi. Tout part de /api/v1, et GET /api/v1 liste ses propres routes sans rien demander.

Un appel dit qui il est dans un en-tête Authorization: Bearer, jamais dans un cookie. C'est soit une clé prise dans Mon compte, soit un jeton acheté avec un mot de passe. Comme il n'y a pas de cookie, rien là-dedans n'a besoin de jeton CSRF.

Les clés API

Un autre programme peut créer des tableaux à votre place, sans navigateur et sans votre mot de passe : une extension de wiki qui ouvre un tableau chaque fois que quelqu'un écrit un compte rendu, par exemple. Mon compte a pour cela une section Clés API : dites à quoi la clé servira, et elle vous est montrée une fois, seule occasion de la lire. Memo n'en garde qu'une empreinte, comme des mots de passe.

La clé ouvre ensuite tout ce qui est sous /api/v1, décrit plus bas, au nom du compte qui l'a faite :

curl -X POST https://memo.example/api/v1/boards \
  -H 'Authorization: Bearer LA-CLÉ' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Compte rendu du 12"}'

{
  "name": "compte-rendu-du-12",
  "room": "/compte-rendu-du-12",
  "title": "Compte rendu du 12",
  "kind": "board",
  "notes": 0,
  "visibility": "open",
  "url": "https://memo.example/compte-rendu-du-12",
  "relation": "owner"
}

Le tableau appartient au compte de la clé : il apparaît dans sa liste, et ce compte peut le fermer aux autres ou le supprimer. Une clé faite par un admin porte le rôle d'admin avec elle : traitez celle-là comme le mot de passe.

La liste dit quand chaque clé a servi la dernière fois, et Reprendre l'annule sur-le-champ. Une clé vaut pour un programme : donnez-en une par programme, pour pouvoir reprendre celle-là seule.

Entrer

curl -X POST https://memo.example/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "vous", "password": "votre mot de passe"}'

La réponse contient un jeton bon pour une semaine d'usage. Cela marche là où Memo garde lui-même les mots de passe, donc avec --auth=local et --auth=ldap. Derrière un portail ou un fournisseur OIDC il n'y a pas de mot de passe à vérifier ici, et c'est une clé qui ouvre la porte. Une clé ne peut pas se déconnecter elle-même : c'est Reprendre, dans Mon compte, qui met fin à une clé.

Les tableaux

Le corps qui crée un tableau prend title, puis kind mis à mindmap pour une carte mentale, template avec le nom d'un modèle (kanban, week, weather), et visibility mis à restricted pour le fermer d'emblée. Le tableau appartient au compte derrière l'appel.

L'administration

Une clé faite par un admin porte le rôle d'admin : un script de nuit peut donc prendre une sauvegarde sans mot de passe écrit dedans. Le revers, c'est qu'une telle clé vaut autant que le mot de passe. Donnez à un script un compte à lui quand vous le pouvez, et reprenez sa clé le jour où le script s'arrête.

Les adresses qui répondent sans porteur

Ce sont celles que le navigateur demande, et un programme peut les demander pareil. Chacune répond à qui a le droit de voir le tableau derrière, par le cookie de session ou par un lien de partage ?s=JETON.

Les deux dernières demandent un navigateur identifié, sauf si --allowAnonymousBoards est activé : c'est la page d'accueil en train de calculer le nom d'un nouveau tableau.

L'ancienne façon de créer un tableau

curl -X POST https://memo.example/api/boards \
  -H 'Authorization: Bearer LA-CLÉ' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Compte rendu du 12"}'

POST /api/boards fait ce que fait POST /api/v1/boards, prend le même corps, et répond toujours pour que ce qui a été écrit avant /api/v1 continue de marcher. Les nouveaux programmes prendront /api/v1/boards, qui accepte aussi un jeton de session et pas seulement une clé.

Ce que les pages s'appellent à elles-mêmes

Les pages du navigateur parlent à un deuxième jeu d'adresses. Elles passent par le cookie de session avec un jeton CSRF dans le corps, elles refusent une requête venue d'une autre origine, et /api/v1 fait le même travail pour un programme. Elles sont listées ici pour que rien dans un journal ne surprenne.

Le reste de ce à quoi le serveur répond, ce sont les pages et les fichiers qu'elles chargent : /, /NOM pour un tableau, /s/JETON pour un lien de partage, /docs, /demo, /login, /register, /account, /admin, /auth/callback où revient un fournisseur OIDC, et les fichiers statiques /css/, /images/, /i18n/, /board/, /mind/, /shared/, /vendor/, les scripts des pages et la police.

Tout ce qui se passe sur un tableau ouvert passe par le WebSocket /ws : les notes, les colonnes, les boîtes, les gens présents. Ce n'est pas une partie de cette API et ses messages changent avec le client qui les parle.