Développement rapide d'API avec Laravel et API Platform

L'auteur est d'avis que davantage de personnes en dehors de l'espace PHP devraient connaître la Plate-forme API. Il s'agit d'un étonnant qui peut structurer l'ensemble de l'API de votre application web en 10 minutes pour commencer, et est livré avec une gamme vertigineuse de fonctionnalités qui transformeront et géreront l'authentification au sein de votre application en modifiant les commutateurs de configuration.

Dans cet article, nous allons prendre une application Laravel existante qui utilise l'API Messages de Vonage et l'ouvrir en tant qu'API web sous différents standards.

Qu'est-ce qu'une plateforme API ?

Ok, voici ce qui est un peu déroutant : API Platform est un framework PHP, mais ce cadre s'appuie ensuite sur Symfony ou Laravel (qui comprendra également d'autres cadres et plates-formes construits au-dessus de ces éléments, tels que Drupal ou WinterCMS). Il s'agit d'un ensemble de configurations et d'attributs que vous pouvez ajouter à la modélisation de votre base de données et à votre dossier de configuration. Il est également livré avec un tableau de bord web complet intégré, pour les tests avec des outils d'API tels que Postman et OpenAPI et les standards de l'API.

Démarrer une application Laravel existante

AKA. "En voici un que j'ai fait plus tôt !" Nous allons utiliser une application qui ne possède qu'une seule entité de base de données : l'humble fichier ToDo, que que j'ai codé dans un article précédent. Elle utilise également l'API Vonage Messages API de Vonage pour envoyer le contenu textuel de la tâche à accomplir à un appareil configuré lorsque l'un des éléments de la tâche à accomplir est coché (comme une notification). Étant donné qu'il s'agit d'une application entièrement fonctionnelle, nous allons commencer par la démarrer avant d'y ajouter l'API Platform.

TLDR ; vous pouvez trouver le code source ici.

Conditions préalables

• git

• PHP 8.3+

• Node 23+ & npm

• Compositeur

• Un Account Vonage

Configuration de l'application Web

1. Récupérez le dépôt sur votre machine : https://github.com/Vonage-Community/blog-messages_native_php

2. Installer les dépendances : composer install

3. Exécuter les migrations en ligne de commande : php artisan migrate

4. Exécutez npm dans la ligne de commande : npm i

5. Dans la ligne de commande, lancez Vite avec npm run dev

6. Dans la ligne de commande, lancez la base de données seeder pour obtenir des données dans notre application : php artisan db:seed

7. Copier l'exemple .env pour en faire un exemple vivant .env dans la ligne de commande : cp .env.example .env

8. Ajoutez vos informations d'identification Vonage au fichier .env fichier.

Cette application utilise l'API Messages de Vonage pour envoyer un SMS lorsque la tâche est terminée. Vous devrez donc créer un Account Vonage puis une application Vonage. Lors de la création de l'application, sélectionnez la fonctionnalité Messages, remplissez les champs des webhooks avec des données fictives et notez l'icône application_id lors de la création. Déplacez le fichier private.key qui est automatiquement téléchargé à la racine des fichiers de votre projet.

Dans le fichier .env vous devez ajouter votre configuration :

VONAGE_APPLICATION_ID="<YOUR_APPLICATION_ID_HERE>"
VONAGE_PRIVATE_KEY_PATH="./private.key"
VONAGE_TO="<YOUR-NUMBER-HERE>"

Notez que VONAGE_PRIVATE_KEY_PATH doit toujours avoir la valeur indiquée ci-dessus, car l'application se résoudra à lire votre clé privée au niveau de la racine.

VONAGE_TO est le numéro auquel vous souhaitez que la notification par SMS soit envoyée.

Vous devrez servir votre application. Je recommande d'utiliser Laravel Herd. Vous pouvez trouver les instructions d'installation ici. Vous pouvez également exécuter le serveur PHP intégré à partir de la ligne de commande : php artisan serve

App up and running!

L'énigme : MVC à API

L'application est écrite comme une application Modèle-Vue-Contrôleur classique avec une pincée de magie frontale gracieuseté de Laravel Livewire. Cependant, considérons deux scénarios :

1. Nous voulons intégrer des outils externes dans notre application, nous devons donc exposer une API.

2. La mise à l'échelle massive signifie que nous devons découpler le front-end et le back-end, ce qui signifie que nous avons un cadre JavaScript distinct, tel que Svelte ou Vue, qui consomme et envoie des données à l'API exposée.

L'incroyable expérience de la plateforme API

Il est temps d'installer API Platform. Ouvrez votre terminal et ajoutez les éléments suivants :

composer require api-platform/laravel

Toujours dans le terminal, terminez l'installation avec la console.

php artisan api-platform:install

C'est tout pour l'installation. Vous ne me croyez pas ? Allez à l'URL de votre projet et ajoutez /api:

We've certainly done -something-Nous avons un modèle ORM Eloquent, Todo. Il se présente comme suit dans l'application :

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Todo extends Model
{
   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */

   protected $casts = [
       'completed' => 'boolean',
   ];
}

Êtes-vous prêt ? La prochaine étape va tout changer, et je vous expliquerai ce qui se passe ensuite. Ajoutez cet attribut :

<?php

namespace App\Models;

use ApiPlatform\Metadata\ApiResource;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

#[ApiResource]
class Todo extends Model
{
   use HasFactory;

   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */
   protected $casts = [
       'completed' => 'boolean',
   ];
}

OK, j'ai ajouté #[ApiResource]. Qu'est-ce que cela fait ? Il rafraîchit le répertoire /api/ du tableau de bord :

An OpenAPI document renders our new magic APIEuh, d'accord ? Alors, quoi, nous avons juste un ensemble complet de routes REST maintenant ? Je suppose que je devrais vérifier cela. Dans la base de données, il y a 10 installations, alors voyons ce qui se passe si j'utilise HTTPie pour lancer la requête GET{id} pour obtenir l'entrée 5 (aussi : n'exposez jamais vos clés primaires dans votre base de données dans le monde réel !)

Absolute cinema!Hein ? Vous venez de créer une API pour moi ? Et si j'envoyais une PATCH pour modifier le titre ?

Suddenly, a wild REST API appearsOK. Nous avons ajouté deux lignes de code et nous avons une API. C'est assez fou.

Approfondir : Normes API et pagination

Les plus perspicaces d'entre vous auront peut-être remarqué que la plate-forme API a adopté par défaut un modèle de structure de données, les champs nommés @contexte et @id. Mais pourquoi ces champs ressemblent-ils à cela ?

La réponse est que la plate-forme API utilise par défaut le format JSON-LD (JSON For Linking Data) par défaut. Il se peut que nous ne voyions ici qu'une seule entité, mais si nous avions une relation entre plusieurs entités, la plateforme API traiterait automatiquement les résultats renvoyés pour vous. Ajoutons, par exemple, une nouvelle entité nommée SubTask. Dans Eloquent, la relation ressemblerait à ceci :

   public function subtasks(): HasMany
   {
       return $this->hasMany(Subtask::class);
   }

L'appel du même point de terminaison produirait une réponse comme celle ci-dessous. N'oubliez pas que j'ai ajouté le code de sérialisation des groupes qui détermine les champs à afficher. Vous pouvez en savoir plus sur la sérialisation de la plateforme API iciou, pour Laravel spécifiquement, utiliser la configuration $visible pour exposer les parties du modèle que vous souhaitez rendre.

{
    "@context": "/api/contexts/Todo",
    "@id": "/api/todos/5",
    "@type": "Todo",
    "id": 5,
    "title": "sample patch request",
    "completed": false,
    "createdAt": "2026-03-10T13:44:23+00:00",
    "updatedAt": "2026-03-11T11:41:13+00:00",
    "subTasks": [
        {
            "@id": "/api/sub_tasks/1",
            "@type": "SubTask",
            "id": 1,
            "title": "Write request body",
            "completed": true
        },
        {
            "@id": "/api/sub_tasks/2",
            "@type": "SubTask",
            "id": 2,
            "title": "Send PATCH request",
            "completed": false
        },
        {
            "@id": "/api/sub_tasks/3",
            "@type": "SubTask",
            "id": 3,
            "title": "Verify API response",
            "completed": false
        }
    ]
}

C'est génial de voir API Platform s'occuper de vos données d'API à votre place. On dirait qu'il est temps de se débarrasser de toutes ces couches de transformation et de tous ces DTO !

Mais, attendez : et si mon standard de choix pour le développement REST n'est pas JSON-LD ? C'est à ce moment-là que nous nous tournons vers la configuration, que vous trouverez dans configuration/api-platform.php.

<?php

/*
* This file is part of the API Platform project.
*
* (c) Kévin Dunglas <dunglas@gmail.com>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

declare(strict_types=1);

use ApiPlatform\Metadata\UrlGeneratorInterface;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Symfony\Component\Serializer\NameConverter\SnakeCaseToCamelCaseNameConverter;

return [
   'title' => 'API Platform',
   'description' => 'My awesome API',
   'version' => '1.0.0',
   'show_webby' => true,
   'routes' => [
       'domain' => null,
       // Global middleware applied to every API Platform routes
       // 'middleware' => [],
   ],
   'resources' => [
       app_path('Models'),
   ],
   'formats' => [
       'jsonld' => ['application/ld+json'],
       // 'jsonapi' => ['application/vnd.api+json'],
       // 'csv' => ['text/csv'],
   ],

(J'ai laissé les droits d'auteur pour donner une idée de l'importance de l'information dans la vie de tous les jours. Kevin Duglas à Kevin Duglas).

Vous voyez, il y a une clé formats dans le tableau de configuration ? Changeons-la :

   'formats' => [
       'jsonld' => ['application/ld+json'],
       'jsonhal' => ['application/hal+json'],
   ],

Si vous envoyez à nouveau la demande, rien ne change. C'est toujours en JSON-LD. Pourquoi ?

Cela fait partie de la mise en œuvre de la négociation de contenu de la plate-forme API. LD-JSON est toujours le première listée, ce qui en fait la clé par défaut. Mais modifiez vos en-têtes de requête en accept: application/hal+json et lancez la requête :

Suddenly, a wild HAL appearsLe pouvoir est désormais entre les mains des consommateurs de votre API, qui peuvent demander le format qu'ils souhaitent.

Cela vous donne également, en tant qu'auteur de votre API, le pouvoir de créer un nouveau point de terminaison sur leur application, par exemple. /api/v2, et simplement le modifier. Allons-y doucement : et si nous voulions simplement transformer notre API en une API GraphQL ? Oui, c'est possible. Vous pouvez le faire en seulement 3 étapes !

1. Installer la plateforme API GraphQL avec Composer dans le navigateur

composer require api-platform/graphql

1. Activez GraphQL dans votre configuration/api-platform.php fichier

   'graphql' => [
       'enabled' => true,
       'nesting_separator' => '__',
       'introspection' => ['enabled' => true],
       'max_query_complexity' => 500,
       'max_query_depth' => 200,
       // 'middleware' => null,
   ],

1. Dirigez-vous vers /api/graphql et que se passe-t-il ?

A Built-in GraphQL sandbox, just for youOui, c'est exact. Vous avez un terrain de jeu GraphQL parce que votre API est désormais GraphQL. Si vous ne me croyez pas :

From REST to GraphQL in mere minutesVous disposez maintenant d'une API GraphQL GraphQL une API REST.

La pagination est l'une des choses que j'ai toujours trouvées très difficiles à mettre en œuvre manuellement. API Platform a une approche qui frise le ridicule lorsqu'il s'agit de simplifier le processus d'intégration de la pagination. Reprenons notre modèle ToDo :

<?php

namespace App\Models;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Symfony\Component\Serializer\Attribute\Groups;

#[ApiResource(normalizationContext: ['groups' => ['read']])]
#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
class Todo extends Model
{
   use HasFactory;

   /**
    * Get the subtasks for the todo.
    */
   #[ApiProperty(readableLink: true)]
   #[Groups(['read'])]
   public function subtasks(): HasMany
   {
       return $this->hasMany(Subtask::class);
   }

   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */
   protected $casts = [
       'completed' => 'boolean',
   ];
}

J'ai ajouté de nouveaux attributs pour formater la relation. Subtask . Pour ajouter la pagination, je vais définir une valeur par défaut pour le nombre d'entités renvoyées par page, puis tester la chaîne de requête de l'URL page URL. Ajoutez l'attribut suivant à la classe :

#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
#[ApiResource(
   normalizationContext: ['groups' => ['read']],
   paginationItemsPerPage: 5,
)]
#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
class Todo extends Model

Et c'est tout. C'est fait. Comme nous avons 10 Todos, cela signifie que nous devrions avoir deux pages - 5 entités renvoyées par page. Vous pouvez donc tester l'ajout de la page 2 :

Magical pagination out of the boxIl a également ajouté des liens de pagination, de la magie.

Conclusion

L'un des points que j'ai soulevés lorsque j'ai parlé de la puissance d'API Platform lors de la conférence API Platform 2025 est que les développeurs PHP qui utilisent ce framework jour après jour ne sont probablement pas conscients de la rareté de ce type de puissance. Je n'ai rencontré aucun autre outil capable de mettre ce type de fonctionnalités entre les mains des développeurs et de les rendre aussi simples. Si vous n'êtes pas du monde PHP, essayez-le, il a rendu le développement d'API à nouveau amusant pour moi.