API : Présentation et configuration

1Présentation

Dans ce tutoriel, nous allons voir comment créer une API. Celle-ci permettra à des services externes de venir se connecter à un service de gestion de bloc-notes.

L'API offre les fonctionnalités suivantes :

  • Lister les notes de l'utilisateur.
  • Lister les tags liés aux notes.
  • Chercher des notes à partir de critères (tag, date, titre).
  • Récupérer le contenu d'une note personnelle.

2Configuration

Ce développement utilise le plugin Api fourni par Temma. Comme indiqué dans la documentation, il faut ajouter le plugin dans le fichier de configuration, avec la configuration de la connexion à la base de données, et la désactivation des sessions : 

<?php

return [
    'application' => [
        // configuration de la base de données
        'dataSources' => [
            'db' => 'mysql://user:password@localhost/dbase'
        ],
        // désactivation des sessions
        'enableSessions' => false,
    ],
    // activation du plugin Api
    'plugins' => [
        '_pre' => [
            '\Temma\Plugins\Api',
        ],
    ],
];

On pourrait penser qu'il faille ajouter à la configuration une instruction pour définir la vue JSON comme vue par défaut. Cela est inutile, le plugin Api s'en charge.

Pour gérer l'authentification des utilisateurs qui se connectent à l'API, le plugin utilise un système de clés publique/privée. Les utilisateurs et les clés sont stockés en base de données. Référez-vous à la documentation du plugin pour connaître la définition des tables à créer.

3Routes

L'API propose une approche RPC, avec une route pour chaque action possible. C'est plus simple que l'approche REST, qui prévoit que la même route effectue des actions différentes en fonction de la méthode HTTP utilisée pour l'appeler.

Le plugin API gère les versions de l'API. Les URLs sont donc préfixées avec "/v1", pour représenter la première version de l'API.

L'API va proposer les URLs suivantes :

  • /v1/tag/list : Retourne une liste de tags.
  • /v1/note/list : Retourne une liste de notes.
  • /v1/note/search : Recherche de notes à partir de critères.
  • /v1/note/get/[id] : Récupère le contenu d'une note.
  • /v1/note/add : Crée une nouvelle note.
  • /v1/note/update/[id] : Modifie une note.
  • /v1/note/remove/[id] : Efface une note.

Si l'authentification n'est pas correcte, une erreur HTTP 401 est renvoyée.
Si un utilisateur authentifié essaye d'accéder à une ressource qui ne lui appartient pas, une erreur HTTP 403 est renvoyée.

3.1/v1/tag/list

Retourne la liste des tags utilisés par les notes de l'utilisateur, avec le nombre de notes correspondant à chaque tag.

Exemple de retour (format JSON) : 

{
    'informatique': 1,
    'web': 1,
    'cuisine': 1
}

3.2/v1/note/list

Retourne la liste des notes de l'utilisateur.

Exemple de retour (format JSON) : 

[
    {
        "id": 123,
        "title": "Sites web intéressants",
        "tags": ["informatique", "web"],
        "creation": "2024-01-01 12:00:00",
        "update": "2024-02-01 16:00:00"
    },
    {
        "id": 456,
        "title": "Cours de cuisine en ligne",
        "tags": ["cuisine", "web"],
        "creation": "2025-01-01 10:00:00",
        "update": "2025-01-01 10:00:00"
    }
]

Retourne une liste de notes appartenant à l'utilisateur, obtenue à partir de critères fournis en paramètres GET.

Paramètres possibles (tous optionnels) :

  • tag (string) : Tag associé aux notes.
  • title (string) : Chaîne de caractères à chercher dans le titre des notes.

La réponse est similaire à celle de l'URL /note/list.

3.4/v1/note/get/[id]

Retourne toutes les données d'une note dont l'identifiant est passé en paramètre sur l'URL.

Exemple de retour (format JSON) : 

{
    "id": 123,
    "title": "Sites web intéressants",
    "tags": ["informatique", "web"],
    "creation": "2024-01-01 12:00:00",
    "update": "2024-02-01 16:00:00"
    "content": "<p>Petite liste de sites :</p>
<ul>
  <li><a href=\"https://www.temma.net/\">Temma</a></li>
</ul>"
}

Si la note demandée n'appartient pas à l'utilisateur, une erreur HTTP 403 est renvoyée.

3.5/v1/note/add

Crée une nouvelle note, en utilisant les données fournies en paramètre POST ou GET.

Paramètres attendus (tous obligatoires) :

  • title (string) : Titre de la note.
  • tag (string | array) : Tag ou liste de tags à associer à la note.
  • content (string) : Contenu de la note au format HTML.

Pour fournir une liste de tags, il faut envoyer plusieurs paramètres nommés tag[].

Cette URL retourne l'identifiant de la note créée.

3.6/v1/note/update/[id]

Met à jour les données de la note dont l'identifiant est fourni en paramètre sur l'URL.

La mise à jour utilise les données fournies en paramètre POST ou GET. Chaque paramètre est optionnel, et un paramètre fourni remplace la valeur enregistrée.

Les paramètres possibles sont :

  • title (string) : Titre de la note.
  • tag (string | array) : Tag ou liste de tags à associer à la note.
  • content (string) : Contenu de la note au format HTML.

Pour fournir une liste de tags, il faut envoyer plusieurs paramètres nommés tag[].

Cette URL retourne la valeur true en cas de succès.

Si la note demandée n'appartient pas à l'utilisateur, une erreur HTTP 403 est renvoyée.

3.7/v1/note/remove/[id]

Efface la note dont l'identifiant est fourni en paramètre sur l'URL.

Cette URL retourne la valeur true en cas de succès.

Si la note demandée n'appartient pas à l'utilisateur, une erreur HTTP 403 est renvoyée.