API

Interfaces de programmation d'application ou Application Programming Interfaces.

Une API est une application.

Quand on parle d’application, on sous-entend souvent une application monolithique (un seul bloc). Depuis 15 ans, on sépare les modules pour que back et front puissent fonctionner séparément. Notamment parce qu’on est dans une ère de micro-services.

Une API est une application sans front (ou peu) qui permet de répondre à une question. C’est une interface qui rend un service. Elle retourne souvent du JSON.

Ex: https://api-adresse.data.gouv.fr/search/?q=8+bd+du+port

Un micro-service est une API dans sa forme minimale (par exemple, un pour la base de données, un pour le front, etc…).

On trouve de nombreuses API gratuites :

api.gouv.fr : toutes les API du domaine public

https://github.com/public-apis/public-apis

chuck noris api

JSON est utilisé parce qu’on fait de l’asynchrone et on affiche la réponse seulement quand elle arrive.

⚙

Outils : API Platform (par Les-Tilleuls) : https://api-platform.com/

Créer une API avec Symfony et API Platform

Projet Github : https://github.com/LSarribouette/mumbling-with-api-platform

Dans un terminal,

se placer dans le bon dossier : cd mon-repertoire

créer un nouveau projet Symfony : symfony new monApi

se placer dans le projet : cd monApi

installer le paquet : composer require api (alias pour API Platform)

lancer le projet : symfony server:start —> l’API fonctionne sur le ‘localhost/api’ (vide pour l’instant)

Dans PhpStorm,

ajouter une base de données de notre choix (ici, PostgreSQL avec Docker), en spécifiant DATABASE_URL dans le .env.local

créer la base de données : symfony console doctrine:database:create

créer une entité :
- installer le paquet : composer require symfony/maker-bundle
- créer l’entité : symfony console make:entity
  - choix du nom : XMen
  - choix si l’on veut la mettre en ressource de l’API (si oui, il crée tout pour nous) : yes
    (ici, on dit oui uniquement si on veut mettre l’entité en public ; on dit non pour les utilisateur, par exemple)
  - choix des propriétés…
  L’entité XMen est créée ainsi que son repository XMenRepository.

mettre à jour la structure de la base de données : symfony console doctrine:schema:update --force

ajouter éventuellement des données via un script SQL

Sur ‘localhost/api’, on voit maintenant l’entité avec :

une documentation générée automatiquement

les routes REST typiques (pour les collections et les items)

les schémas de l’entité aux format .json et .jsonId

📌

Pour aller plus loin : https://api-platform.com/docs/distribution/ https://api-platform.com/docs/core/operations/

Sécurité : restreindre l’accès aux méthodes HTTP

Il est possible de restreindre l’accès à certaines méthodes HTTP comme DELETE, soit aux utilisateurs ayant un certain rôle, soit complètement.

Lors de la création de l’entité, on a choisi de la mettre en ressource de l’API. Un attribut #[ApiResource] a été ajouté à la classe :

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use App\Repository\XMenRepository;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: XMenRepository::class)]
#[ApiResource]
class XMen
{...}

On peut choisir de donner accès uniquement à la méthode GET en ajoutant un attribut #[Get] (ou plusieurs #[Get, Post]) en dessous du précédent :

#[ORM\Entity(repositoryClass: XMenRepository::class)]
#[ApiResource]
#[Get]
class XMen
{...}

De nombreux attributs sont disponibles : #[Get], #[GetCollection], #[Post], #[Put], #[Delete], #[Patch]…

On peut également choisir de donner accès aux méthodes selon le rôle de l’utilisateur en ajoutant un attribut #[IsGranted].

Interroger une API

Objectif : récupérer la liste des X-Men en JSON et remplir la liste dans la page HTML.

Dans un IDE (ici VSCode),

créer une page HTML avec un titre, une liste, une balise <script> pour JavaScript

<!DOCTYPE html>
<html lang="fr">
<head>
    <title>Interroger mon API</title>
</head>
<body>
    <h1>Liste des X-Men</h1>
    <ul id="maListe"></ul>
    <script>
        // a completer
    </script>
</body>
</html>

Pour récupérer la liste des X-Men en JSON, trois options sont possibles :

XML HTTP Request (non)

AJAX avec jQuery (non)

Fetch avec en paramètre l’URL de l’API que l’on veut joindre (oui)

Dans la balise <script>,

récupérer la liste en JSON :
- méthode fetch() avec en paramètre l’URL de la méthode souhaitée (ici, la GET pour la collection) finissant par .json
- un call back asynchrone avec .then pour transformer la chaîne de texte en JSON
  (une méthode anonyme où on met dans la parenthèse avant la flèche le retour de la commande précédente et après la flèche on met la fonction à exécuter — si on met rien, ce sera un return)
- un autre .then pour afficher le résultat

<script>
  fetch('http://127.0.0.1:8000/api/x_mens.json') 
  .then((reponse) => reponse.json())
  .then((json) => console.log(json));
</script>

Lorsqu’on lance le Live Server, la liste est visible dans l’inspecteur, onglet Console.

ℹ️

S’il y a un problème avec l’API, on peut le voir dans l’inspecteur, onglet Réseau.

ℹ️

Si erreur de cross-origin, on peut modifier le .env à la dernière ligne CORS_ALLOW_ORIGIN et on lui rajouter une condition *|local.

Pour remplir la liste dans la page HTML, on complète le script JavaScript :

faire une boucle sur le JSON où à chaque objet trouvé, on crée une <li>
1. on récupère l’<ul> avec son id
1. on boucle sur le tableau
1. pour chaque ligne, on crée une <li>
1. on remplit le texte de la <li> avec le pseudo
1. on accroche la <li> à la <ul>
  (quelque chose qui n’est raccroché à rien n’est pas visible)

<script>
    fetch('http://127.0.0.1:8000/api/x_mens.json') 
    .then((reponse) => reponse.json())
    .then((json) => {
        let monUl = document.getElementById("maListe");
        for (const uneXMen of json) {
        let monLi = document.createElement('li');
        monLi.innerText = uneXMen.pseudo;
        monUl.appendChild(monLi);
        }
    })
</script>

ℹ️

Pareil mais avec un Twig ? > Après avoir ajouter les paquets nécessaires (twig et symfony/asset), > créer un contrôleur MainController avec une méthode index() qui retourne le Twig index.html.twig, > et ajouter le bout de code correspondant dans le {% block body %}.

Format Hydra

https://api-platform.com/docs/core/extending-jsonld-context/

https://www.hydra-cg.com/

Un Hydra est un autre format qui contient tout ce qu’il y avait dans le fichier JSON, avec en plus d’autres informations comme le nombre d’éléments.

Si ce nombre est supérieur à 20, on a un URL qui permet d’avoir accès aux 20 éléments suivants.

ℹ️

Par défaut, le format de notre API est Hydra donc on n’a pas besoin d’ajouter l’extension à la fin de l’URL : on avait précisé “.json” pour spécifier le format JSON.

On peut également boucler sur un Hydra en utilisant member.

<script>
  fetch('http://10.22.0.254:8002/api/superheroes') 
  .then((reponse) => reponse.json())
  .then((json) => {
    let monUl = document.getElementById("maListe");
    for (const uneXMen of json["hydra:member"]) {
      let monLi = document.createElement('li');
      monLi.innerText = uneXMen.pseudo;
      monUl.appendChild(monLi);
    }
  })
</script>

Authentification

Il est possible de limiter l’accès à une API à des utilisateurs ayant certains droits.

Pour cela, on utilise des JSON Web Token (JWT) grâce au paquet LexikJWTAuthenticationBundle.

ℹ️

On crée un utilisateur avec make:user (et non pas make:auth).

📌

Pour aller plus loin : https://jwt.io/ https://api-platform.com/docs/core/jwt/#jwt-authentication