« Programmation PHP avec Symfony/API » : différence entre les versions

Un livre de Wikilivres.
Contenu supprimé Contenu ajouté
Ligne 22 : Ligne 22 :
===== MaxDepth() =====
===== MaxDepth() =====
Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un ''MaxDepth(1)'' sur l'attribut ''client->contrat'' fera que la liste des clients comprendra tous les contrats mais pas leurs produits.
Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un ''MaxDepth(1)'' sur l'attribut ''client->contrat'' fera que la liste des clients comprendra tous les contrats mais pas leurs produits.

===== Évènements =====
API Platform ajoute plus d'une dizaine d'évènements donc les priorités sont définies dans EventPriorities<ref>https://api-platform.com/docs/core/events/</ref>.

Par exemple, pour modifier un JSON POST envoyé, utiliser EventPriorities::PRE_DESERIALIZE.

L'évènement suivant POST_DESERIALIZE contient les objets instanciés à partir du JSON.


== Triplet de bibliothèques ==
== Triplet de bibliothèques ==

Version du 21 décembre 2020 à 19:21

Pour créer une interface de programmation (API) REST avec Symfony, il existe plusieurs bibliothèques :

  • API Platform[1], tout-en-un qui utilise les annotations des entités pour créer les APIs (donc pas besoin de créer des contrôleurs ou autres). Par défaut il permet de sérialiser les flux en JSON (dont JSON-LD, JSON-HAL, JSON:API), XML (dont HTML), CSV, YAML, et même en GraphQL[2].
  • Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur.

API Platform

Installation

 composer require api

Utilisation

API Platform se configure par des annotations dans les entités.

Logo

Le GraphQL de la version 1.1 passe par le schéma REST, et ne bénéficie donc pas du gain de performances attendu sans overfetching.

Annotations

API\ApiResource()

Définit les noms et méthodes REST (get, post...) des routes de l'API.

MaxDepth()

Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un MaxDepth(1) sur l'attribut client->contrat fera que la liste des clients comprendra tous les contrats mais pas leurs produits.

Évènements

API Platform ajoute plus d'une dizaine d'évènements donc les priorités sont définies dans EventPriorities[3].

Par exemple, pour modifier un JSON POST envoyé, utiliser EventPriorities::PRE_DESERIALIZE.

L'évènement suivant POST_DESERIALIZE contient les objets instanciés à partir du JSON.

Triplet de bibliothèques

Installation

FOS REST

FOSRestBundle apporte des annotations pour créer des contrôleurs d'API[4]. Installation :

    composer require "friendsofsymfony/rest-bundle"

Puis dans config/packages/fos_rest.yaml :

fos_rest:
    view:
        view_response_listener:  true
    format_listener:
        rules:
            - { path: '^/',  prefer_extension: true, fallback_format: ~, priorities: [ 'html', '*/*'] }
            - { path: ^/api, prefer_extension: true, fallback_format: json, priorities: [ json ] }

Doc

Toute API doit exposer sa documentation avec ses routes et leurs paramètres. NelmioApiDocBundle est un de générateur de documentation automatique à partir du code[5], qui permet en plus de tester en ligne. En effet, pour éviter de tester les API en copiant-collant leurs chemins dans une commande cURL ou dans des logiciels plus complets comme Postman[6], on peut installer une interface graphique ergonomique qui allie documentation et test en ligne :

    composer require "nelmio/api-doc-bundle"

Son URL se configure ensuite dans routes/nelmio_api_doc.yml :

app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

A ce stade l'URL /api/doc affiche juste un lien NelmioApiDocBundle.

Sérialiseur

Enfin pour la sérialisation, on distingue plusieurs solutions :

  • symfony/serializer, qui donne des contrôleurs extends AbstractFOSRestController et des méthodes aux annotations @Rest\Post()[7].
  • jms/serializer-bundle, avec des contrôleurs extends RestController et des méthodes aux annotations @ApiDoc().
  • Le service fos_rest.service.serializer.
symfony/serializer
    composer require "symfony/serializer"
jms/serializer-bundle
    composer require "jms/serializer-bundle"

Utilisation

Maintenant /api/doc affiche les méthodes des différents contrôleurs API. Voici un exemple :

<?php

namespace App\Controller;

use FOS\RestBundle\Controller\AbstractFOSRestController;
use FOS\RestBundle\View\View;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class APIController extends AbstractFOSRestController
{
    /**
     * Test the API
     * @Route("/api/test", methods={"GET"})
     * @param Request $request
     * @return View
     */
    public function testAction(Request $request): View
    {
        return View::create('ok');
    }
}

Maintenant dans /api/doc, cliquer sur /api/test, puis "Ty it out" pour exécuter la méthode de test.

Références