Grégoire Hébert

@gheb_dev

Programme

Introduction
Créer une API
Générer un modèle de données à partir des vocabulaires ouverts
Générer une interface d'administration avec React
Générer une web app avec React
Déployer en production avec Docker et Kubernetes

Programme

Rappel sur les APIs : REST, HATEOAS, hypermedia, GraphQL
Les APIs au coeur du web aujourd’hui
JavaScript et les Progressive Web Apps
API Platform, Symfony et React
Les bénéfices immédiats

Programme

Mettre en place son environnement de développement avec Docker
Créer son modèle de données
Sérialiser ses données
Valider ses données
Filtrer ses données
Paginer ses données
Gérer des utilisateurs
Sécuriser ses données
Créer des opérations personnalisées
Se brancher aux évènements
Personnaliser la documentation OpenAPI
Personnaliser la documentation Hydra
Uploader des images
Tester son API avec Behat
Mettre en cache ses données

Le web évolue !

De plus en plus de Javascript webapps, et Google est capable de les parcourir.
Les utilisateurs passent plus de temps sur mobile que sur leur machine: des sites responsive, ou des apps mobile sont plus que nécessaire.
JSON-LD, Schema.org, Hydra: Linked Data & l e web semantic sont de plus en plus utilisé.

API, le nouveau cœur du web

Un seul point d'accès aux données
Encapsulation de la logique métier
Homogénéité des données pour tout les supports.

API Platform

A framework for the new API-first web

3 composants !

Une API web
Une Application web statique (SPA)
Une Administration web dynamique

L'API web

Lecture / Écriture centralisée des donnée

Contient toute la logique métier

Conçue avec PHP & API-Platform

Stateless pour une meilleure expansion horizontale sans contrainte de session.

L'application web

Ou tout autre client (mobile,etc...)

Détiens la logique de présentation

Est chargé une seule fois (Single Page Application

Requête l'API pour recevoir ou modifier les données en AJAX

Uniquement composé d'HTML, Javascript, et assets CSS

Peux être hébergée sur un CDN

L'admin web

Permet de gérer vos données

Est généré dynamiquement grâce à la doc Hydra

Ne contient aucune logique métier

Est écrit en React avec Admin-on-rest

Peux être hébergée sur un CDN

StandAlone

3 dépôt Git pour 3 projets et 3 CI
1 dépôt pour les rassembler ~~(et dans les ténèbres les lier)~~
3 domaines
Le routing est réalisé côté client.

Bénéfices immédiats

Rapide

les Assets sont chargés depuis un CDN
Plus aucun chargement par la suite si ce n'est le strict nécessaire pour chaque requête
quantité de données en transit minimisée
Les réponses de l'API peuvent être mise en cache par le proxy

Extensible et robuste

L'application frontale n'est qu'un jeu de fichiers statiques.
API Stateless : Ajout et suppression de serveurs / conteneurs sur demande

Confort de développement

Un formulaire pour générer le code ? Faites le en JS, Oubliez les formulaires Symfony.
Ré-utilisez votre API pour tous vos besoins : App mobile native, App TV, Appareil connecté, ou client bureau.
Donnez accès à vos utilisateurs et partenaires un accès aux données brutes à travers l'API

Bénéfices à long terme

Une structure éprouvée : La centralisation de l'API, c'est aussi la centralisation de la logique métier. Moins de duplication lorsque votre application grandi.
Refactoring facilité : Modifier un composant n'impacte pas les autres.
Gestion de projet simplifiée : différentes équipes peuvent travailler sur les différentes app.

Formats, (open) standards, patterns

HTTP + REST + JSON

Fonctionne sur toutes les plaformes
Léger
Stateless
HTTP possède un puissant système de cach
Extensible (JSON-LD, Hydra, Swagger, HAL...)
Il existe de nombreux outils de développement

HATEOAS / Linked Data

Hypermedia as the Engine of Application State

Hypermedia: IRI comme identifiant
Possibilité de référencer des données externe (liens hypertexte par exemple)
clients génériques

JSON-LD

Json for Linked data

Standard W3C depuis 2014
Facile, c'est du json !
Déjà utilisé par Gmail, GitHub, BBC, Microsoft...
Adapté aux technologies du web sémantique : RDF, SPARQL, triple store...

{
  "@context": "/contexts/PostalAddress",
  "@id": "/postal_addresses",
  "@type": "hydra:PagedCollection",
  "hydra:totalItems": 1,
  "hydra:itemsPerPage": 30,
  "hydra:firstPage": "/postal_addresses",
  "hydra:lastPage": "/postal_addresses",
  "hydra:member": [
    {
      "@id": "/postal_addresses/1",
      "@type": "http://schema.org/PostalAddress",
      "id": 1,
      "addressCountry": "France",
      "postalCode": "75008",
      "streetAddress": "6 Rue Balzac"
    }
  ]
}

Schema.org

Défini un large panel d'éléments : people, creative work, events, products, chemicals...
Créé et interprếté par Google, Bing, Yahoo! et Yandex
Massivement utilisé, et suivi par le W3C
Peut être utilisé avec le HTML, RDF et JSON-LD
Peut être étendu (Vocabulaire personnalisé)

Hydra

Décrit une API REST avec du JSON-LD
Permet l'écriture de données
Permet de découvrir automatiquement l'API
Draft W3C (Work In Progress)

Autres formats supportés

Swagger
HAL
API Problem
raw JSON
CSV
YAML
XML

API Platform: La promesse

API avec support complet de Swagger + JSON-LD + Hydra + HAL en quelques minutes
Documentation auto-générée
Définition de spec et de tests avec Behat
Authentification avec JWT ou OAuth
CORS & cache HTTP
All the tools you love: Doctrine ORM, Monolog, Swiftmailer...
Un générateur de modèle grâce à Schema.org

API Platform <3 Symfony

Conçu à partir de Symfony flex
Installez n'importe quel Bundle SF existant
Suit les bonnes pratiques SF
Intégrable dans une application existante SF
(Optionnel) Optimisé pour doctrine

Créer une API

$ wget https://github.com/api-platform/api-platform/archive/v2.2.0.tar.gz
$ tar xzvf v2.2.0.tar.gz
$ cd api-platform-2.2.0

Télécharger le squelette

ou bien utiliser composer

$ composer create-project api-platform/api-platform formation

# Start Docker
$ docker-compose up -d

# Création de la bdd
$ docker-compose exec php bin/console doctrine:schema:create

Démarrage du projet

https://localhost

Sérialiser ses données

Créer votre première entité

<?php

declare(strict_types=1);

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;

/**
 * The mailing address.
 *
 * @see http://schema.org/PostalAddress Documentation on Schema.org
 *
 * @ORM\Entity
 * @ApiResource(iri="http://schema.org/PostalAddress")
 */
class PostalAddress
{
    /**
     * @ORM\Id
     * @ORM\Column(type="string")
     * @ORM\GeneratedValue(strategy="UUID")
     *
     * @var string
     */
    private $uuid;

    /**
     * @var string|null The country. For example, USA. You can also provide the two-letter \[ISO 3166-1 alpha-2 country code\](http://en.wikipedia.org/wiki/ISO\_3166-1).
     *
     * @ORM\Column(type="text", nullable=true)
     * @ApiProperty(iri="http://schema.org/addressCountry")
     */
    private $addressCountry;

    /**
     * @var string|null The postal code. For example, 94043.
     *
     * @ORM\Column(type="text", nullable=true)
     * @ApiProperty(iri="http://schema.org/postalCode")
     */
    private $postalCode;

    /**
     * @var string|null The street address. For example, 1600 Amphitheatre Pkwy.
     *
     * @ORM\Column(type="text", nullable=true)
     * @ApiProperty(iri="http://schema.org/streetAddress")
     */
    private $streetAddress;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function setAddressCountry(?string $addressCountry): void
    {
        $this->addressCountry = $addressCountry;
    }

    public function getAddressCountry(): ?string
    {
        return $this->addressCountry;
    }

    public function setPostalCode(?string $postalCode): void
    {
        $this->postalCode = $postalCode;
    }

    public function getPostalCode(): ?string
    {
        return $this->postalCode;
    }

    public function setStreetAddress(?string $streetAddress): void
    {
        $this->streetAddress = $streetAddress;
    }

    public function getStreetAddress(): ?string
    {
        return $this->streetAddress;
    }
}

Créer la table associée

$ docker-compose exec php bin/console \
doctrine:schema:update --force

api-# \d+ postal_address
 id              | integer | not null  | plain    |              | 
 address_country | text    |           | extended |              | 
 postal_code     | text    |           | extended |              | 
 street_address  | text    |           | extended |              |

La documentation

Est à jour !

http(s)://localhost:8080/

Vous obtenez :

Support CRUD des relations et données
Validation des données
Pagination de collections
Gestion de la sérialisation
Gestion dynamique des routes
Propriétés exposées filtrables
Sorting
Point d'entrée Hypermedia

GET /postal_addresses

{
  "@context": "/contexts/PostalAddress",
  "@id": "/postal_addresses",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/postal_addresses/1",
      "@type": "http://schema.org/PostalAddress",
      "id": 1,
      "addressCountry": "France",
      "postalCode": "75008",
      "streetAddress": "6 Rue Balzac"
    }
  ],
  "hydra:totalItems": 1
}

Magie ?

Le bundle expose les données grâce aux metadata suivantes:

Doctrine ORM
Validator constraints
Serializer groups
PHPDoc
Vos propres Metadata Loaders

Support complet de JSON-LD, Hydra et Schema.org

API de données auto-decouvrable !

Documentation et Sandbox

Swagger UI Détecte et documente automatiquement les ressources exposées.

Génération dynamique d'admin

L'admin s'appuie sur la documentation Hydra pour générer les opérations CRUD nécessaire !

Génération de client statique

Le client s'appuie sur la documentation Hydra pour générer les vues et composants REACT !

Valider ses données

<?php

declare(strict_types=1);

namespace App\Entity;

use ...
use Symfony\Component\Validator\Constraints as Assert;

/**
 * The mailing address.
 *
 * @see http://schema.org/PostalAddress Documentation on Schema.org
 *
 * @ORM\Entity
 * @ApiResource(iri="http://schema.org/PostalAddress")
 */
class PostalAddress
{
    // ...

    /**
     * @var string|null The street address. For example, 1600 Amphitheatre Pkwy.
     *
     * @Assert\NotBlank
     *
     * @ORM\Column(type="text", nullable=true)
     * @ApiProperty(iri="http://schema.org/streetAddress")
     */
    private $streetAddress;


    // ...
}

Grégoire Hébert

Programme

Programme

Programme

Le web évolue !

API, le nouveau cœur du web

API Platform

A framework for the new API-first web

3 composants !

L'API web

L'application web

L'admin web

StandAlone

Bénéfices immédiats

Rapide

Extensible et robuste

Confort de développement

Bénéfices à long terme

Formats, (open) standards, patterns

HTTP + REST + JSON

HATEOAS / Linked Data

JSON-LD

Schema.org

Hydra

Autres formats supportés

API Platform: La promesse

API Platform <3 Symfony

Créer une API

Télécharger le squelette

ou bien utiliser composer

Démarrage du projet

Sérialiser ses données

Créer votre première entité

Créer la table associée

La documentation

Est à jour !

Vous obtenez :

GET /postal_addresses

Magie ?

Le bundle expose les données grâce aux metadata suivantes:

Support complet de JSON-LD, Hydra et Schema.org

Documentation et Sandbox

Génération dynamique d'admin

Génération de client statique

Valider ses données

C'est tout !

formation api-platform 2.2

More from Grégoire Hébert