R&eacute;&eacute;criture de la documentation et nouveau site web

Une communaut&eacute; en pleine croissance

Les prochaines &eacute;tapes

Exposer une API en quelques secondes gr&acirc;ce au nouveau syst&egrave;me des configuration et de m&eacute;tadonn&eacute;es

L&rsquo;int&eacute;gration de Docker

Un g&eacute;n&eacute;rateur de mod&egrave;le de donn&eacute;es am&eacute;lior&eacute;

La n&eacute;gociation de contenu et le support int&eacute;gr&eacute; pour JSON-LD, Hydra, HAL, YAML, CSV et XML.

Une UI pratique et une documentation Swagger 2 automatique

De nouveaux filtres

S&eacute;curis&eacute; par d&eacute;faut, respectant les recommandations de l&rsquo;OWASP

Am&eacute;lioration des performances

Mise &agrave; disposition en tant que composants autonomes, dissoci&eacute;s de Symfony et Doctrine

Qualit&eacute; du code et tests automatis&eacute;s

Sortie d'API Platform V2 !

Nouveaut&eacute;s dans le composant Serializer de Symfony 3.1

Quelles sont les prochaines &eacute;tapes ?

Contribuez !

API Platform en quelques chiffres

API Platform 2.0 : les nouveaut&eacute;s

API Platform : qu&rsquo;est-ce que c&rsquo;est ?

Les changements architecturaux

Installation avec Composer

Installation avec Docker (travail en cours)

Les objectifs d&rsquo;API Platform

Core : nouveau syst&egrave;me de configuration

Core : nouvelle configuration de filtres

Core : op&eacute;rations et groupes de s&eacute;rialisation

Core : nouveau syst&egrave;me d&rsquo;&eacute;v&eacute;nements

Le flot de requ&ecirc;tes

Core : op&eacute;rations et contr&ocirc;leurs personnalis&eacute;s

Pourquoi les utiliser ?

Autres points d&rsquo;extension

Core : n&eacute;gociation de contenu

G&eacute;n&eacute;rateur de sch&eacute;ma : nouvelles fonctionnalit&eacute;s

Autres nouveaut&eacute;s

Il y a presque un an &#8211; déjà ! -, <a href="https://les-tilleuls.coop/fr/blog/article/api-platform-beta-le-framework-web-php-nouvelle-generation">nous vous présentions API Platform, un framework PHP construit sur Symfony pour les projets API-First</a> dont nous sommes les créateurs. Quelques mois après le lancement de la première version stable, <a href="https://les-tilleuls.coop/fr/blog/article/les-tilleuls-coop-lance-api-platform-1-0">API Platform 1.0</a>, nous sommes heureux de vous annoncer que la première alpha d’API Platform 2.0 est enfin disponible ! À cette occasion, nous vous proposons de découvrir les changements et les nouvelles fonctionnalités apportés par cette version.



<h2>API Platform : qu’est-ce que c’est ?</h2>



<h3>Les objectifs d’API Platform</h3>



Avant de commencer, un petit rappel s’impose. API Platform est un framework qui permet de créer en quelques minutes des API Web modernes complètes et puissantes avec une liberté totale en termes de redéfinition et de personnalisation. Il est conforme avec la dernière génération de normes et d’usages : il supporte les Linked Data, HATEOAS et le web sémantique (JSON-LD, Hydra, <a href="https://schema.org/">Schema.org</a>, JWT…).



<h3>Roadmap</h3>



La version 1.1 d’API Platform a été dévoilée le 16 mai dernier. Elle n’apporte pas de nouvelles fonctionnalités mais corrige quelques bugs et améliore la sécurité. Cette version est construite sur Symfony 2.8 mais elle est parfaitement compatible avec Symfony 3.0. Elle sera maintenue jusque novembre 2019 (tout comme Symfony 2.8).



La première alpha d’API Platform 2.0 est disponible depuis la même date. Sa version stable est prévue pour le mois de juin.



<h3>API Platform en quelques chiffres</h3>



En quelques mois d’existence, API Platform a récolté <a href="https://github.com/api-platform/api-platform">plus de 650 étoiles sur GitHub</a>. Le framework compte 5 membres dans sa Core Team (<a href="https://twitter.com/samuelroze">Samuel Roze</a>, <a href="https://twitter.com/teohhanhui">Teoh Han Hui</a>, <a href="https://twitter.com/tfidry">Théo Fidry</a>, <a href="https://twitter.com/vincentchalamon">Vincent Chalamon</a> et <a href="https://twitter.com/dunglas">Kévin Dunglas</a>) et plus de 60 contributeurs. Des entreprises de toutes tailles l’utilisent déjà dans le cadre de leurs projets : c’est notamment le cas de <a href="https://sensiolabs.com/">SensioLabs</a>, <a href="http://www.smile.fr/">Smile</a>, <a href="http://www.thefork.com/">La Fourchette/TripAdvisor</a> ou encore <a href="http://www.beinsports.com/">BeIN Sports</a>. &nbsp;



<h2>API Platform 2.0 : les nouveautés</h2>



<h3>Les changements architecturaux</h3>



API Platform 2.0 n’est pas une réécriture complète. Cette version corrige quelques limites de conception présentes dans la version 1 mais n’est plus rétrocompatible. &nbsp;&nbsp;



API Platform Core (anciennement DunglasApiBundle) n’est plus un bundle Symfony mais une bibliothèque PHP indépendante construite avec des composants Symfony. Elle est utilisable en PHP brut (le support de Laravel ne devrait pas tarder) mais Symfony est toujours (et restera) le choix privilégié (bundle inclus).



Cette version implémente le modèle <a href="https://github.com/pmjones/adr">Action-Domain-Responder</a> en utilisant <a href="http://symfony.com/doc/current/reference/events.html#kernel-events">les événements du kernel Symfony</a>. Il est plus flexible et plus facile à personnaliser.



L’utilisation de PHP 7+ permet l’utilisation des nouvelles fonctionnalités comme l’opérateur ??, les type-hints scalaires et les types de retour dans le code d’API Platform.



Dans Symfony 3.1+, une bonne partie du code d’API Platform v1 été déplacé dans les composants Serializer, PropertyInfo et PropertyAccess de Symfony.



<h4>Installation avec Composer</h4>



<code>composer create-project api-platform/api-platform myapp v2.0.0-alpha.1</code>



<h4>Installation avec Docker (travail en cours)</h4>



<code>git clone git@github.com:api-platform/core.git &amp;&amp; cd core &amp;&amp; docker-compose up</code>



<h3>Core : nouveau système de configuration</h3>



API Platform 2.0 introduit le support du XML. Il reste encore à ajouter le support du mapping des propriétés. Cette version supporte également le format YAML. Là encore, il reste à ajouter le support du mapping des propriétés. Le nouveau système de configuration d’API Platform 2.0 permet également la pagination, les relations, le tri ou encore le filtrage.&nbsp;



<h3>Core : nouvelle configuration de filtres</h3>



Les filtres disponibles (Doctrine) sont les suivants :



<ul><li>Recherche (comme % %) ;</li><li>Ordre (tri) ;</li><li>Date ;</li><li>Amplitude ;</li><li>Booléen ;</li><li>Numérique.</li></ul>



<h3>Core : opérations et groupes de sérialisation</h3>



Vous pouvez personnaliser les opérations et groupes de sérialisation. Seules les opérations GET /tasks et GET /tasks{id} sont disponibles. Toutes les autres opérations (POST, PUT, DELETE) ne sont pas enregistrées. Lorsque vous utilisez cette configuration, les déclarations doivent être explicites.



Différents groupes de sérialisation sont appliqués par opération. Seul « text » est affiché dans la liste, « text » et « status » sont affichés pour l’IRI de l’item et la désérialisation n’est pas impactée (utilisez la clef denormalization_context).



Cela fonctionne également avec les mappings XML et YAML.



<h3>Core : nouveau système d’événements</h3>



Le système d’événements de la version 1 a été retiré (PRE_CREATE, POST_CREATE, PRE_VALIDATE…). API Platform 2.0 s’appuie sur les événements Symfony. Cette version implémente également le modèle Action-Domain-Responder. Les Event Listeners sont appliqués uniquement sur les requêtes gérées par API Platform (et non sur les requêtes Symfony standards). Pour hooker votre logique personnalisée, vous pouvez utiliser les événements kernel : sécurité (isGranted), en-tête de cache, validation, persistence, appel à des API externes, mail…



<h4>Le flot de requêtes</h4>



La requête kernel.request permet de deviner le meilleur format de réponse (négociation de contenu).



La requête controller permet de :



<ul><li style="text-align: justify;">Récupérer les données depuis le système de persistence (GET, PUT, DELETE) ;</li><li style="text-align: justify;">Désérialiser la requête (GET, PUT, DELETE) ;</li><li style="text-align: justify;">Retourner une entité (GET, POST, PUT, DELETE), une série d’entités ou une pagination (cGET).</li></ul>



Kernel.view (priorité 20) valide les données (POST, PUT). En priorité 10, elle permet de faire persister les données (POST, PUT, DELETE) et en priorité 0, elle sérialise les données et les transforme dans une réponse.



<h3>Core : opérations et contrôleurs personnalisés</h3>



<h4>Pourquoi les utiliser ?</h4>



L’utilisation des opérations et des contrôleurs personnalisés permet de créer des extrémités orientées services ou non REST. Elle permet également de personnaliser les URLs et de gérer les sous-ressources (exemple : /tasks/{id}/comments/{c_id}). Quand les événements kernel ne suffisent pas, hookez votre propre logique, mais préférez toujours les événements kernel lorsque cela est possible.



<h4>Autres points d’extension</h4>



Les autres points d’extension (qui existent également dans la v1) sont les suivants :



<ul><li style="text-align: justify;">Les filtres, pour manipuler la requête HTTP et les requêtes Doctrine (filtrage, tri) si elles sont utilisées ;</li><li style="text-align: justify;">Les Data Providers, pour extraire des données de la couche de persistance ;</li><li style="text-align: justify;">Les normaliseurs (Serializer Symfony) ;</li><li style="text-align: justify;">Les encodeurs (Serializer Symfony) ;</li><li style="text-align: justify;">Les validateurs (Validation Symfony) ;</li><li style="text-align: justify;">Tous les points d’extension Symfony (services, configuration) Doctrine (si vous l’utilisez).</li></ul>



<h3>Core : négociation de contenu</h3>



La négociation de contenu offre la possibilité de sélectionner le meilleur format à utiliser selon le header HTTP Accept. &nbsp;Elle est construite sur la bibliothèque Negotiation 2 de William Durand (comme FOSRest) et se connecte au composant Serializer de Symfony. Elle permet de retourner des formats hypermédia (HAL, JSON-API…) ou non (JSON brut, XML brut…).



<h3>Générateur de schéma : nouvelles fonctionnalités</h3>



La version 1.1 du générateur de schéma est incluse dans API Platform 1.1 et 2. Il est disponible en PHAR et est compatible avec Symfony 3. Il supporte :



<ul><li style="text-align: justify;">MongoDB ;</li><li style="text-align: justify;">Les Embeddables Doctrine ;</li><li style="text-align: justify;">Les propriétés et entités personnalisées ;</li><li style="text-align: justify;">Les groupes de sérialisation.</li></ul>



Il peut exploiter n’importe quel vocabulaire RDF(a) et permet de personnaliser les attributs unique, nullable et l’annotation @Column de Doctrine.



<h3>Autres nouveautés</h3>



API Platform 2.0 introduit le support de MongoDB (WIP), la pagination (configurable et avec un nouveau format Hydra), la gestion des relations, la sérialisation des types complexes (comme les objets imbriqués) et le support de PSR-6 pour de meilleures performances. Cette version comprend également de nouveaux filtres. &nbsp;&nbsp;



<h4>Nouveautés dans le composant Serializer de Symfony 3.1</h4>



Le composant Serializer de Symfony 3.1 introduit la sérialisation des objets imbriqués, la sérialisation des arbres avec l’annotation @MaxDepth, le normalizer data: URl vers SplFileInfo pour l’upload de fichiers et le normalizer d’objets DateTime. Sa performance est améliorée, notamment avec le support de PSR-6. &nbsp;



<h2>Quelles sont les prochaines étapes ?</h2>



Au niveau des outils côté client, il faut encore améliorer <a href="https://github.com/api-platform/admin">le bridge ng-admin/Hydra</a>, qui est pour l’instant en alpha, et&nbsp;<a href="https://github.com/coopTilleuls/hm-admin">l’admin Hydra Angular 2</a> (en cours). &nbsp;Il reste également à intégrer Guzzle et à créer des générateurs CRUD Angular 2, React, Vue.js etc. en utilisant la documentation Hydra.



Il faut aussi ajouter le support de JSONAPI et HAL (rien de bien compliqué grâce à la nouvelle architecture d’API Platform) et de Swagger 2.0.



<h3>Contribuez !</h3>



Si vous souhaitez contribuer au projet, n’hésitez pas ! Nous avons besoin de votre aide pour :



<ul><li style="text-align: justify;">Finir et améliorer la documentation ;</li><li style="text-align: justify;">Terminer le support de MongoDB ;</li><li style="text-align: justify;">Tester, tester et tester encore ;</li><li style="text-align: justify;"><a href="https://github.com/api-platform/website">Améliorer le site web de API Platform</a> ;</li><li style="text-align: justify;">Faire connaître le projet.</li></ul>



Un grand merci à tous ceux qui participent activement au développement d’API Platform. Stay tuned pour la suite des événements !

La première alpha d’API Platform 2.0 est disponible !

L&rsquo;approche API First, un atout pour les entreprises


Le 4 août dernier, la célèbre plateforme de partage de photos Instagram a officiellement lancé son API publicitaire, Instagram Ads API. Intégrée au service depuis 2013 pour les Etats-Unis et seulement mars 2015 pour l’Hexagone, la publicité était jusqu’alors réservée à une poignée de grandes entreprises comme Coca Cola, Air France ou Guerlain. Pour l’heure, seuls quelques partenaires triés sur le volet ont accès à l’API &#8211; Ampush, Kenshoo ou Hootsuite, pour en citer quelques-uns. Cela devrait toutefois changer dans les mois à venir puisqu’elle s’ouvrira à tous les annonceurs avant la fin de l’année. L’API permettra ainsi aux entreprises de toutes tailles d’acheter des publicités et de gérer une campagne sur Instagram sans avoir à passer par l’un de ses commerciaux. Très bien, me direz-vous, mais&#8230; Une API, c’est quoi au juste ?



<h2>API : définition</h2>



Comment le bouton « Like »&nbsp;de Facebook a-t-il colonisé la toile, des plateformes e-commerce aux journaux en ligne ? Par quel moyen les entreprises intègrent-elles leur flux de tweets à leur site internet ? La réponse à ces questions tient en trois lettres :&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://fr.wikipedia.org/wiki/Interface_de_programmation">API</a>. Derrière cette abréviation obscure se cache une appellation qui ne l’est pas moins, Application Programming Interface. Une API est&nbsp;une interface de programmation&nbsp;qui permet à deux programmes ou applications de&nbsp;communiquer en utilisant le même langage&nbsp;et de&nbsp;se partager des données. Celles-ci peuvent être transmises dans différents&nbsp;formats. Parmi les plus utilisés figurent&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://fr.wikipedia.org/wiki/JavaScript_Object_Notation">JSON</a>, basé sur JavaScript et apprécié pour sa simplicité, ou encore&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://fr.wikipedia.org/wiki/Extensible_Markup_Language">XML</a>, riche et puissant. Ils vont déterminer la structure donnée aux informations. Chaque API est construite selon&nbsp;un style d’architecture, c’est à dire un ensemble de contraintes à respecter. Les plus communs sont&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://fr.wikipedia.org/wiki/Representational_State_Transfer">REST</a>&nbsp;(Reprensentational State Transfer), &nbsp;et&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://fr.wikipedia.org/wiki/SOAP">SOAP</a>&nbsp;(Simple Object Access Protocol), basé sur XML.&nbsp;Aujourd’hui, les API proposent&nbsp;de multiples services dans des domaines variés&nbsp;: vidéo (<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://developers.google.com/youtube/?hl=fr">Youtube</a>), cartographie (<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://developers.google.com/maps/">Google Maps</a>), envoi de SMS, d’e-mailings (<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://www.ymlp.com/fr/">YMLP</a>,&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://apidocs.mailchimp.com/api/">Mailchimp</a>), météo (<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.accuweather.com/en/fr/france-weather">AccuWeather</a>), réseaux sociaux (<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://dev.twitter.com/rest/public">Twitter</a>,&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://developers.facebook.com/docs/apis-and-sdks">Facebook</a>)&#8230;&nbsp;Parce qu’un exemple est plus parlant qu’une définition abstraite, penchons-nous sur un cas pratique.



<h3>Un cas concret : l’API Instagram</h3>



Une blogueuse souhaite faire apparaître les photos de son compte Instagram sur son site WordPress. Pour ne pas avoir à les publier manuellement une à une, il va falloir que WordPress récupère les données dont il a besoin sur Instagram et que l’application lui&nbsp;donne accès à ses fonctionnalités. C’est là que l’API entre en jeu : elle va&nbsp;servir d’intermédiaire entre les plateformes&nbsp;et&nbsp;leur permettre d’intéragir&nbsp;même si elles n’ont pas été développées avec les mêmes technologies. On parle d’<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://fr.wikipedia.org/wiki/Interop%C3%A9rabilit%C3%A9">interopérabilité</a>. Via l’<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://instagram.com/developer/">API Instagram</a>, le&nbsp;client, WordPress, va donc transmettre à la base de données du&nbsp;service, Instagram, une&nbsp;requête&nbsp;afin d’importer les photos. Instagram va ensuite lui faire parvenir une&nbsp;réponse&nbsp;à travers l’API, et la boucle est bouclée.



<h2>Pourquoi utiliser les API ?</h2>



Si les développeurs sont friands d’API, c’est qu’elles&nbsp;facilitent considérablement leur travail. Elles constituent en effet&nbsp;un gain de temps&nbsp;non négligeable puisqu’elles leur fournissent des briques de base avec lesquelles travailler directement pour&nbsp;des réalisations de qualité. Nul besoin de réinventer la roue ! En outre, si certaines sont payantes &#8211; ou du moins en partie, c’est le cas de&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.zdnet.fr/actualites/api-de-google-maps-des-requetes-desormais-payantes-39765242.htm">l’API de Google Maps</a>&nbsp;-, bon nombre d’entre elles sont gratuites et libres d’accès : une importante&nbsp;source d’économie.&nbsp;Notre équipe utilise régulièrement les API dans nos travaux de programmation, et nous sommes également en mesure de&nbsp;les créer sur demande. Des sociétés et groupes comme&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.alicesgarden.fr/">Walibuy</a>,&nbsp;40ème&nbsp;dans le top 100 du e-commerce français,&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.exaqtworld.com/">Exaqtworld</a>&nbsp;ou encore&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://www.geophyle.com/">Géophyle</a>&nbsp;ont fait appel à nos services dans ce domaine.&nbsp;



<h2>L’approche API First, un atout pour les entreprises</h2>



Pour une entreprise,&nbsp;le fait de construire une API au centre de son&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://fr.wikipedia.org/wiki/Syst%C3%A8me_d%27information">système d&rsquo;information</a>&nbsp;(SI)&nbsp;&#8211; ce qu&rsquo;on appelle l&rsquo;approche API First&nbsp;&#8211;&nbsp;présente pléthore d&rsquo;avantages.&nbsp;Cela permet notamment :



<ul><li style="text-align: justify; font-weight: 400;">par la suite, de développer aisément d’autres sites et applications qui s&rsquo;appuieront sur les données fournies par l&rsquo;API ;</li><li style="text-align: justify; font-weight: 400;">en centralisant la logique métier de l&rsquo;entreprise dans l&rsquo;API, de garantir à son/ses site(s) internet et son/ses application(s) un cycle de vie indépendant avec, éventuellement, une équipe de programmeurs propre à chaque entité ;</li><li style="text-align: justify; font-weight: 400;">de faciliter l&rsquo;interaction des partenaires, fournisseurs et clients avec les données et le système d&rsquo;information de l&rsquo;entreprise &#8211; c&rsquo;est la notion d&rsquo;<a href="https://fr.wikipedia.org/wiki/Hyperm%C3%A9dia">hypermédia</a> ;</li><li style="text-align: justify; font-weight: 400;">en simplifiant la connexion aux logiciels métiers (<a href="http://fr.wikipedia.org/wiki/ERP">ERP</a>, plateformes e-commerce, <a href="http://fr.wikipedia.org/wiki/Gestion_de_la_relation_client">CRM</a>&#8230;), de maximiser l&rsquo;interopérabilité de ses applications grâce au format <a href="https://schema.org/">Schema.org</a> et au vocabulaire <a href="http://www.w3.org/ns/hydra/spec/latest/core/">Hydra</a> tout en améliorant le référencement naturel (SEO).</li></ul>



Pour faciliter la mise en place de ce type de projet nous avons créé&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://api-platform.com">API Platform</a>, un framework web PHP de nouvelle génération construit sur Symfony&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="https://les-tilleuls.coop/?s=API+Platform+%28beta%29">que nous vous présentions tout récemment</a>.&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.smile.fr/Services/Agence">Smile</a>,&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.exaqtworld.com/">Exaqtworld</a>&nbsp;et&nbsp;<a style="font-family: inherit; line-height: 1.42857; background-color: #ffffff;" href="http://www.tripadvisor.com/">TripAdvisor</a>&nbsp;l’utilisent déjà. Et vous ?



<a href="https://les-tilleuls.coop/contact/" target="_blank" rel="noopener">Si vous avez un projet, n’hésitez pas à nous contacter pour en discuter !</a>

Comprendre les API

Troisième et dernière partie du tutoriel consacré à <a href="https://api-platform.com/">API Platform</a>, le&nbsp;framework PHP développé par notre gérant <a href="https://dunglas.fr/">Kévin Dunglas</a> et auquel nous contribuons activement. Cet article est toujours&nbsp;<a href="https://dunglas.fr/2015/06/introducing-dunglass-api-platform-beta-the-next-generation-php-framework/">disponible en version anglaise</a>.

<h2>Le client Angular</h2>

Prérequis : <a href="https://nodejs.org/">Node.js</a> et <a href="https://www.npmjs.com/">NPM</a> doivent être installés.

Dunglas’ API Platform est indépendant de toute technologie côté client. Vous pouvez utiliser la plate-forme, le langage ou le framework de votre choix. Pour illustrer les portes qu’ouvre l’adoption d’une architecture API-first et la facilité de développement d’une application monopage, nous allons créer un petit client AngularJS.

Gardez à l’esprit qu’il ne s’agit pas d’un tutoriel AngularJS et que je ne prétends pas suivre les bonnes pratiques AngularJS. Il s’agit juste d’un exemple visant à montrer à quel point le développement d’applications devient simple lorsque toute la logique métier est encapsulée dans une API. La seule responsabilité de notre client de blog AngularJS est d’afficher les informations récupérées par l’API (couche présentation).

L’application AngularJS est totalement indépendante de l’API. C’est une application HTML/JS/CSS qui interroge une API via AJAX. Elle a son propre dépôt Git et est hébergée sur son propre serveur web. Puisqu’elle ne contient que des assets, elle peut même être hébergée directement sur un Content Delivery Network comme Amazon CloudFront ou Akamai (nous hébergeons la démo sur GitHub Pages).

Pour échafauder notre application AngularJS, nous allons utiliser le <a href="https://github.com/yeoman/generator-angular">générateur Angular</a> officiel de <a href="http://yeoman.io/">Yeoman</a>. Installez le générateur puis générez un squelette de client :

<pre class="wp-block-preformatted lang:default decode:true">mkdir blog-client
cd blog-client
yo angular blog</pre>

Yeoman vous posera des questions. Nous voulons que l’application reste minimale :

<ul><li>n’installez pas le support de Sass ;</li><li>installez Twitter Bootsrap (c’est optionnel, mais l’application aura meilleur aspect) ;</li><li>décochez tous les modules Angular suggérés.</li></ul>

Toutefois, nous allons installer <a href="https://github.com/mgonto/restangular">Restangular</a>, un super client REST pour Angular qui s’intègre bien à API Platform :

<pre class="wp-block-preformatted lang:default decode:true">bower install --save lodash restangular</pre>

Le générateur Angular est accompagné de l’outil de build <a href="http://gruntjs.com/">Grunt</a>. Il compile les assets (réduction, compression) et peut exposer la web app via son serveur intégré. D’ailleurs, lancez-le.

<pre class="wp-block-preformatted lang:default decode:true">grunt serve</pre>

DunglasApiBundle fournit dans sa documentation <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/angular-integration.md">un guide d’intégration Restangular</a>. Une fois configuré, Restangular va fonctionner avec l’API JSON-LD/Hydra comme avec n’importe quelle autre API REST classique.

Ensuite, modifiez le fichier <code>app/app.js</code> pour enregistrer Restangular et le configurer correctement :

<pre class="wp-block-preformatted lang:default decode:true">// app/scripts/app.js'use strict';/**
 * @ngdoc overview
 * @name blogApp
 * @description
 * # blogApp
 *
 * Main module of the application.
 */
angular
 .module('blogApp', ['restangular'])
 .config(['RestangularProvider', function (RestangularProvider) {
 // The URL of the API endpoint
 RestangularProvider.setBaseUrl('http://localhost:8000'); // JSON-LD @id support
 RestangularProvider.setRestangularFields({
 id: '@id'
 });
 RestangularProvider.setSelfLinkAbsoluteUrl(false); // Hydra collections support
 RestangularProvider.addResponseInterceptor(function (data, operation) {
 // Remove trailing slash to make Restangular working
 function populateHref(data) {
 if (data['@id']) {
 data.href = data['@id'].substring(1);
 }
 } // Populate href property for the collection
 populateHref(data); if ('getList' === operation) {
 var collectionResponse = data['hydra:member'];
 collectionResponse.metadata = {}; // Put metadata in a property of the collection
 angular.forEach(data, function (value, key) {
 if ('hydra:member' !== key) {
 collectionResponse.metadata[key] = value;
 }
 }); // Populate href property for all elements of the collection
 angular.forEach(collectionResponse, function (value) {
 populateHref(value);
 }); return collectionResponse;
 } return data;
 });
 }])
;</pre>

Prenez soin de changer l’URL de base avec celle de votre API en production (PROTIP : utilisez <a href="https://github.com/werk85/grunt-ng-constant">grunt-ng-constant</a>).

Et voici le contrôleur qui récupère la liste des articles et nous permet d’en créer une nouvelle :

<pre class="wp-block-preformatted lang:default decode:true">// app/scripts/controllers/main.js'use strict';/**
 * @ngdoc function
 * @name blogApp.controller:MainCtrl
 * @description
 * # MainCtrl
 * Controller of the blogApp
 */
angular.module('blogApp')
 .controller('MainCtrl', function ($scope, Restangular) {
 var blogPostingApi = Restangular.all('blog_postings');
 var peopleApi = Restangular.all('people'); function loadPosts() {
 blogPostingApi.getList().then(function (posts) {
 $scope.posts = posts;
 });
 } loadPosts();
 peopleApi.getList().then(function (people) {
 $scope.people = people;
 }); $scope.newPost = {};
 $scope.success = false;
 $scope.errorTitle = false;
 $scope.errorDescription = false; $scope.createPost = function (form) {
 blogPostingApi.post($scope.newPost).then(function () {
 loadPosts(); $scope.success = true;
 $scope.errorTitle = false;
 $scope.errorDescription = false; $scope.newPost = {};
 form.$setPristine();
 }, function (response) {
 $scope.success = false;
 $scope.errorTitle = response.data['hydra:title'];
 $scope.errorDescription = response.data['hydra:description'];
 });
 };
 });</pre>

Comme vous pouvez le voir, il est très facile d’interroger l’API avec Restangular. La bibliothèque émet automatiquement des requêtes HTTP au serveur et hydrate des objets JavaScript “magiques” correspondant aux réponses JSON qui peuvent être manipulés pour modifier les ressources distantes (via des requêtes <code>PUT</code>, <code>POST</code> et <code>DELETE</code>).

Nous tirons également parti de la gestion des erreurs côté serveur pour afficher de jolis messages quand les données soumises sont invalides ou lorsque quelque chose ne va pas.

Et la vue correspondante bouclant sur les publications et affichant le formulaire et les erreurs :

<pre class="wp-block-preformatted lang:default decode:true">&lt;!-- app/views/main.html --&gt;&lt;!-- ... --&gt;&lt;article ng-repeat="post in posts" id="{{ post['@id'] }}" class="row marketing"&gt;
 &lt;h1&gt;{{ post.name }}&lt;/h1&gt;
 &lt;h2&gt;{{ post.headline }}&lt;/h2&gt; &lt;header&gt;
 Date: {{ post.datePublished | date:'medium' }}
 &lt;span ng-hide="post.isFamilyFriendly"&gt; - &lt;b&gt;NSFW&lt;/b&gt;&lt;/span&gt;
 &lt;/header&gt; &lt;p&gt;{{ post.articleBody }}&lt;/p&gt; &lt;footer&gt;
 Section: {{ post.articleSection }}
 &lt;/footer&gt;
&lt;/article&gt;&lt;form name="createPostForm" ng-submit="createPost(createPostForm)" class="row marketing"&gt;
 &lt;h1&gt;Post a new article&lt;/h1&gt; &lt;div ng-show="success" class="alert alert-success" role="alert"&gt;Post published.&lt;/div&gt;
 &lt;div ng-show="errorTitle" class="alert alert-danger" role="alert"&gt;
 &lt;b&gt;{{ errorTitle }}&lt;/b&gt;&lt;br&gt; {{ errorDescription }}
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;input ng-model="newPost.name" placeholder="Name" class="form-control"&gt;
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;input ng-model="newPost.headline" placeholder="Headline" class="form-control"&gt;
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;textarea ng-model="newPost.articleBody" placeholder="Body" class="form-control"&gt;&lt;/textarea&gt;
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;label for="author"&gt;Author&lt;/label&gt;
 &lt;select ng-model="newPost.author" ng-options="person['@id'] as person.name for person in people" id="author"&gt;
 &lt;/select&gt;
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;input ng-model="newPost.datePublished" placeholder="Date published" class="form-control"&gt;
 &lt;/div&gt; &lt;div class="form-group"&gt;
 &lt;input ng-model="newPost.articleSection" placeholder="Section" class="form-control"&gt;
 &lt;/div&gt; &lt;div class="checkbox"&gt;
 &lt;label&gt;
 &lt;input type="checkbox" ng-model="newPost.isFamilyFriendly"&gt; is family friendly?
 &lt;/label&gt;
 &lt;/div&gt; &lt;button type="submit" class="btn btn-primary"&gt;Submit&lt;/button&gt;
&lt;/form&gt;</pre>

C’est la fin de ce tutoriel ! Notre client blog est prêt et il fonctionne ! Vous vous souvenez de l’ancienne façon de créer des applications web synchrones ? Que pensez-vous de cette nouvelle approche ? C’est plus simple et beaucoup plus puissant, vous ne trouvez pas ?

Bien entendu, il reste encore pas mal de boulot afin d’obtenir un client fini incluant le routing, le support de la pagination et permettant d’intégrer du JSON-LD brut dans le HTML généré pour les moteurs de recherche (utilisez <a href="https://github.com/mgonto/restangular/issues/100">le hook Response Extractor</a> fourni par Restangular). &nbsp;Dans la mesure où il s’agit uniquement de tâches Angular, cela dépasse le cadre de cette introduction à API Platform. Ajouter de telles fonctionnalités au client est néanmoins un bon exercice. N’hésitez pas à partager vos snippets dans les commentaires.

La facilité de développement et de la puissance d’API Platform vous ont convaincu ? Donnez-nous votre feedback dans les commentaires !

<h2>Roadmap</h2>

La première bêta est prête et il y a des tâches à accomplir avant la première version stable :

<ul><li>Le code est presque prêt et est déjà utilisé par des entreprises comme Les-Tilleuls.coop, Smile, le groupe Trip Advisor et ExaqtWorld. Mais API Platform doit encore être fiabilisé. La première tâche avant la release est de tester et corriger les bugs.</li><li>La documentation doit être améliorée. Ce tutoriel sera la base de la toute nouvelle documentation qui est en cours d’écriture. Un site internet dédié est également en préparation.</li><li>Nous avons également besoin de plus d’intégration (documentation ou bibliothèques) avec des technologies frontend populaires !</li></ul>

J’espère publier la première version stable très prochainement. Vous pouvez m’y aider <a href="https://github.com/dunglas/api-platform">en contribuant</a> (rapports de bug, documentation, code). Tout est hébergé sur GitHub et les Pull Requests sont les bienvenues.

<h2>Remerciements</h2>

Je remercie tout spécialement <a href="https://github.com/sroze">Samuel Roze</a> (ancien membre de l’équipe de Les-Tilleuls.coop et aujourd’hui employé chez Inviqa), <a href="https://github.com/theofidry">Théo Fidry</a> et <a href="https://github.com/fabiengasser">Fabien Gasser</a> (Smile), <a href="https://github.com/ogizanagi">Maxime Steinhausser</a>, <a href="https://github.com/jderusse">Jérémy Derussé</a> et <a href="https://twitter.com/schtroumpf_luc">Luc Vieillescazes</a> (SensioLabs) ainsi que <a href="https://github.com/MLKiiwy">Michaël Labrut</a> (La Fourchette) d’avoir contribué au projet en y apportant du code, de la documentation et une tonne de bonnes idées.

API Platform n’aurait jamais vu le jour sans les formidables technologies et bibliothèques qu’il utilise comme bases, particulièrement Symfony, Doctrine, JSON-LD, Hydra et Schema.org. Un grand merci à tous leurs contributeurs.

<h2>Support commercial</h2>

Vous avez peur d’essayer ce nouveau framework ? Le support commercial est déjà disponible : <a href="https://les-tilleuls.coop/">Les-Tilleuls.coop</a> est en mesure de développer vos logiciels basés sur API Platform (et Symfony). Notre équipe d’ingénieurs expérimentés propose des prestations de formation et de consulting. <a href="https://les-tilleuls.coop/contact/">N&rsquo;hésitez pas à nous contacter pour en savoir plus !</a>

API Platform (beta) : le framework web PHP nouvelle génération (partie 3)

Cette semaine, nous vous dévoilons la deuxième partie du tutoriel consacré à <a href="https://api-platform.com/">API Platform</a>, un framework développé par notre gérant <a href="https://dunglas.fr/">Kévin Dunglas</a> et auquel nous contribuons activement. Cet article est <a href="https://dunglas.fr/2015/06/introducing-dunglass-api-platform-beta-the-next-generation-php-framework/">également disponible en version anglaise</a>.

<h2>Exposer l’API</h2>

Nous avons un modèle de données fonctionnel appuyé par une base de données. A présent, nous allons créer une API REST hypermédia grâce à un autre composant de Dunglas’ API Platform : <a href="https://github.com/dunglas/DunglasApiBundle">DunglasApiBundle</a>.

Comme PHP Schema, il est déjà préinstallé et configuré correctement. Nous avons juste besoin de déclarer les ressources que nous souhaitons exposer.

Exposer une collection de ressources consiste à enregistrer un nouveau <a href="http://symfony.com/doc/current/book/service_container.html">service Symfony</a>. Pour notre application de blog, nous allons exposer, à travers l’API, les deux classes d’entités générées par PHP Schema :

<code>BlogPosting&nbsp;</code>(article du blog) et <code>Person</code> &nbsp;(auteur de l’article) :

<pre class="wp-block-preformatted lang:yaml decode:true"># app/config/services.ymlservices:
 resource.blog_posting:
 parent: "api.resource"
 arguments: [ "AppBundle\Entity\BlogPosting" ]
 tags: [ { name: "api.resource" } ] resource.person:
 parent: "api.resource"
 arguments: [ "AppBundle\Entity\Person" ]
 tags: [ { name: "api.resource" } ]</pre>

Et voilà, notre API est déjà terminée ! Il n’y a pas plus simple !

Démarrez le serveur web de développement intégré : <code>app/console server:start</code>

Puis ouvrez <code>http://localhost:8000/doc</code> avec un navigateur web.

Grâce au support de DunglasApiBundle par <a href="https://github.com/nelmio/NelmioApiDocBundle">NelmioApiDocBundle</a> et à son intégration avec API Platform, vous obtenez sans plus d’efforts une documentation de l’API lisible par les humains et automatiquement générée. Celle-ci comprend également un bac à sable pour tester l’API.

Vous pouvez également utiliser votre client HTTP préféré pour interroger l’API. Je vous recommande vivement d’utiliser <a href="https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm">Postman</a>. Il est plus bas niveau que la sandbox et il vous permettra d’inspecter facilement les requêtes et réponses JSON.

Ouvrez <code>http://localhost:8000</code> avec Postman. Cette URL est le point d’entrée de l’API. Il vous donne accès à toutes les ressources exposées. Comme vous pouvez le voir, l’API retourne du JSON-LD compressé. Pour une meilleure lisibilité, les snippets JSON ont été indentés dans ce document.

<h2>Essayer l’API</h2>

Ajoutez une personne appelée Kévin&nbsp;en lançant une requête POST sur <code>http://localhost:8000/people&nbsp;</code>avec le document JSON suivant comme corps brut :

<pre class="wp-block-preformatted lang:default decode:true">{"name": "Kévin"}</pre>

Les données sont insérées dans la base de données. Le serveur répond avec une représentation en JSON-LD de la ressource nouvellement créée. Grâce à PHP Schema, la propriété <code>@type</code> du document JSON-LD fait référence à un type Schema.org :

<pre class="wp-block-preformatted lang:default decode:true">{
 "@context": "/contexts/Person",
 "@id": "/people/1",
 "@type": "http://schema.org/Person",
 "name": "Kévin"
}</pre>

La spécification JSON-LD est pleinement supportée par le bundle. Vous voulez une preuve ? Parcourez <code>http://localhost:8000/contexts/Person</code>.

Par défaut, l’API autorise les méthodes HTTP <code>GET</code> (récupérer, pour les collections et les items), <code>POST</code> (créer), <code>PUT</code> (mettre à jour) et <code>DELETE</code>. <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/operations.md">Vous pouvez ajouter et supprimer n’importe quelle autre opération si vous le souhaitez</a>. Essayez !

À présent, parcourez <code>http://localhost:8000/people</code> :

<pre class="wp-block-preformatted lang:default decode:true">{
 "@context": "/contexts/Person",
 "@id": "/people",
 "@type": "hydra:PagedCollection",
 "hydra:totalItems": 1,
 "hydra:itemsPerPage": 30,
 "hydra:firstPage": "/people",
 "hydra:lastPage": "/people",
 "hydra:member": [
 {
 "@id": "/people/1",
 "@type": "http://schema.org/Person",
 "name": "Kévin"
 }
 ]
}</pre>

La pagination est également supportée.

Il est temps de publier notre premier article. Exécutez une requête POST sur <code>http://locahost:8000/blog_posting</code> avec le document JSON suivant dans son corps :

<pre class="wp-block-preformatted lang:default decode:true">{
 "name": "Dunglas's API Platform is great",
 "headline": "You'll love that framework!",
 "articleBody": "The body of my article.",
 "articleSection": "technology",
 "author": "/people/1",
 "isFamilyFriendly": "maybe",
 "datePublished": "2015-05-11"
}</pre>

Oups… La propriété <code>isFamilyFriendly</code> est booléenne. Notre JSON contient une chaîne incorrecte. Fort heureusement, le bundle est assez intelligent pour détecter l’erreur : il utilise les annotations de <a href="https://symfony.com/doc/current/book/validation.html">validation Symfony</a> générées précédemment par PHP Schema. Il retourne un message d’erreur détaillé au <a href="http://www.w3.org/ns/hydra/spec/latest/core/#description-of-http-status-codes-and-errors">format de sérialisation des erreurs Hydra</a> :

<pre class="wp-block-preformatted lang:default decode:true">{
 "@context": "/contexts/ConstraintViolationList",
 "@type": "ConstraintViolationList",
 "hydra:title": "An error occurred",
 "hydra:description": "isFamilyFriendly: This value should be of type boolean.n",
 "violations": [
 {
 "propertyPath": "isFamilyFriendly",
 "message": "This value should be of type boolean."
 }
 ]
}</pre>

Corrigez le corps et envoyez la requête de nouveau :

<pre class="wp-block-preformatted lang:default decode:true">{
 "name": "Dunglas's API Platform is great",
 "headline": "You'll love that framework!",
 "articleBody": "The body of my article.",
 "articleSection": "technology",
 "author": "/people/1",
 "isFamilyFriendly": true,
 "datePublished": "2015-05-11"
}</pre>

Nous avons réglé le problème ! En passant, vous avez appris comment travailler avec des relations. Dans une API hypermédia, chaque ressource est identifiée par un IRI unique (une URL est un IRI). Les IRI se trouvent dans la propriété <code>@id</code> de chaque document JSON-LD généré par l’API et vous pouvez les utiliser comme références pour créer des relations comme nous l’avons fait dans le précédent extrait de code pour la propriété auteur.

Le framework API Platform est assez intelligent pour comprendre <a href="http://php.net/manual/en/datetime.formats.date.php">n’importe quel format de date supporté par les fonctions date PHP</a>. En production, nous vous recommandons le format spécifié par le <a href="http://tools.ietf.org/html/rfc3339">RFC 3339</a>.

Nous avons déjà une API REST hypermédia puissante (toujours sans écrire la moindre ligne de PHP), mais ce n’est pas fini.

Notre API est auto-découvrable. Ouvrez <code>http://localhost:8000/vocab</code> et jetez un oeil au contenu. Les capacités de l’API sont entièrement décrites dans un format lisible par les machines : ressources disponibles, propriétés et opérations, description des éléments, propriétés lisibles et enregistrables, types retournés et attendus…

En ce qui concerne les erreurs, l’API toute entière est décrite avec <a href="http://www.w3.org/ns/hydra/spec/latest/core/">le vocabulaire Hydra Core</a>, un standard web ouvert pour décrire des APIs REST hypermédia en JSON-LD. Un client ou une librairie compatible avec Hydra est capable d’interagir avec l’API sans rien connaître d’elle ! Le client Hydra le plus populaire est <a href="http://www.markus-lanthaler.com/hydra/console/">Hydra Console</a>. Utilisez-le pour ouvrir une URL de l’API et vous obtiendrez une interface de gestion plutôt jolie.

Vous pouvez aussi essayer la toute nouvelle bibliothèque <a href="https://github.com/bergos/hydra-core">Hydra Core Javascript</a>.

DunglasApiBundle offre de nombreuses autres fonctionnalités incluant :

<ul><li>des <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/filters.md">filtres</a> ;</li><li>des <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/serialization-groups-and-relations.md">groupes de sérialisation et l’intégration de la ressource enfant</a> ;</li><li><a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/operations.md">opérations personnalisées</a> : désactiver des méthodes, créer des opérations personnalisées, URL et controllers ;</li><li><a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/data-providers.md">fournisseurs de données</a> : récupérer et modifier des données à travers un web-service ou une base de données MongoDB ou n’importe quoi d’autre à la place de Doctrine ORM ;</li><li>un puissant <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/the-event-system.md">système d’événements</a>.</li></ul>

Lisez <a href="https://github.com/dunglas/DunglasApiBundle/">la documentation qui lui est dédiée</a> pour voir comment les exploiter et comment y insérer votre code.

<h2>Spécifier et tester l’API</h2>

<a href="http://docs.behat.org/">Behat</a> (un <a href="http://en.wikipedia.org/wiki/Behavior-driven_development">framework de développement piloté par le comportement</a>) est préconfiguré avec des contextes utiles pour spécifier et tester les documents REST API et JSON.

Avec Behat, vous pouvez écrire la spécification de l’API (comme les scénarios utilisateurs) dans un langage naturel puis exécuter des scénarios contre l’application pour valider son comportement.

Créez un fichier <a href="http://docs.behat.org/en/latest/guides/1.gherkin.html">Gherkin</a> contenant les scénarios que nous avons exécutés manuellement au chapitre précédent :

<pre class="wp-block-preformatted lang:default decode:true">Feature: Blog
 In order to post news
 As a client software developer
 I need to be able to retrieve, create, update and delete authors and posts trough the API. # "@createSchema" creates a temporary SQLite database for testing the API
 @createSchema
 Scenario: Create a person
 When I send a "POST" request to "/people" with body:
 """
 {"name": "Kévin"}
 """
 Then the response status code should be 201
 And the response should be in JSON
 And the header "Content-Type" should be equal to "application/ld+json"
 And the JSON should be equal to:
 """
 {
 "@context": "/contexts/Person",
 "@id": "/people/1",
 "@type": "http://schema.org/Person",
 "name": "Kévin"
 }
 """ Scenario: Retrieve the user list
 When I send a "GET" request to "/people"
 Then the response status code should be 200
 And the response should be in JSON
 And the header "Content-Type" should be equal to "application/ld+json"
 And the JSON should be equal to:
 """
 {
 "@context": "/contexts/Person",
 "@id": "/people",
 "@type": "hydra:PagedCollection",
 "hydra:totalItems": 1,
 "hydra:itemsPerPage": 30,
 "hydra:firstPage": "/people",
 "hydra:lastPage": "/people",
 "hydra:member": [
 {
 "@id": "/people/1",
 "@type": "http://schema.org/Person",
 "name": "Kévin"
 }
 ]
 }
 """ Scenario: Throw errors when a post is invalid
 When I send a "POST" request to "/blog_postings" with body:
 """
 {
 "name": "Dunglas's API Platform is great",
 "headline": "You'll that framework!",
 "articleBody": "The body of my article.",
 "articleSection": "technology",
 "author": "/people/1",
 "isFamilyFriendly": "maybe",
 "datePublished": "2015-05-11"
 }
 """
 Then the response status code should be 400
 And the response should be in JSON
 And the header "Content-Type" should be equal to "application/ld+json"
 And the JSON should be equal to:
 """
 {
 "@context": "/contexts/ConstraintViolationList",
 "@type": "ConstraintViolationList",
 "hydra:title": "An error occurred",
 "hydra:description": "isFamilyFriendly: This value should be of type boolean.n",
 "violations": [
 {
 "propertyPath": "isFamilyFriendly",
 "message": "This value should be of type boolean."
 }
 ]
 }
 """ # "@dropSchema" is mandatory to cleanup the temporary database on the last scenario
 @dropSchema
 Scenario: Post a new blog post
 When I send a "POST" request to "/blog_postings" with body:
 """
 {
 "name": "Dunglas's API Platform is great",
 "headline": "You'll that framework!",
 "articleBody": "The body of my article.",
 "articleSection": "technology",
 "author": "/people/1",
 "isFamilyFriendly": true,
 "datePublished": "2015-05-11"
 }
 """
 Then the response status code should be 201
 And the response should be in JSON
 And the header "Content-Type" should be equal to "application/ld+json"
 And print last JSON response
 And the JSON should be equal to:
 """
 {
 "@context": "/contexts/BlogPosting",
 "@id": "/blog_postings/1",
 "@type": "http://schema.org/BlogPosting",
 "articleBody": "The body of my article.",
 "articleSection": "technology",
 "author": "/people/1",
 "datePublished": "2015-05-11T00:00:00+02:00",
 "headline": "You'll that framework!",
 "isFamilyFriendly": true,
 "name": "Dunglas's API Platform is great"
 }
 """</pre>

L’intégration de Behat fournie par API Platform comporte également une base de données SQLite temporaire dédiée aux tests. Elle est prête à l’emploi.

Exécutez simplement <code>bin/behat</code>. Tout devrait être vert :

<pre class="wp-block-preformatted lang:default decode:true">4 scenarios (4 passed)
21 steps (21 passed)</pre>

Vous obtenez alors une puissante API hypermédia exposant des données structurées, spécifiée et testée grâce à Behat. Et toujours sans aucune ligne de PHP !

C’est très utile pour le prototypage et le développement rapide d’applications (RAD). Mais le framework est conçu pour fonctionner dans un environnement de production. Il bénéficie de solides points d’extension et a été optimisé pour les sites à très haut trafic (API Platform propulse la nouvelle version du site web d’un grand média international).

<h2>Autres fonctionnalités</h2>

API Platform dispose d’un grand nombre d’autres fonctionnalités et peut être étendu avec les bibliothèques PHP et les bundles Symfony. <a href="https://twitter.com/ApiPlatform">Restez connectés</a>, une documentation plus fournie et d’autres livres de recettes sont en préparation !

Voici une liste non exhaustive de ce que vous pouvez faire avec API Platform :

<ul><li style="text-align: justify;">ajouter <a href="https://github.com/dunglas/DunglasApiBundle/blob/master/Resources/doc/fosuser-bundle.md">un système de gestion des utilisateurs</a> (intégration de FOSUser) ;</li><li style="text-align: justify;"><a href="https://github.com/lexik/LexikJWTAuthenticationBundle">sécuriser l’API avec JWT</a> (LexikJwtAuthenticationBundle) ou <a href="https://github.com/FriendsOfSymfony/FOSOAuthServerBundle">OAuth</a> (FosOAuthServer) ;</li><li style="text-align: justify;"><a href="http://foshttpcachebundle.readthedocs.org/">ajouter un reverse proxy Varnish et adopter une stratégie de cache HTTP d’expiration ou d’invalidation</a> (FosHttpCache) ;</li><li style="text-align: justify;"><a href="https://github.com/dunglas/DunglasAngularCsrfBundle">ajouter la protection CSRF quand l’authentification de l’API repose sur les cookies</a> (DunglasAngularCsrfBundle &#8211; préférez utiliser un mode d’authentification stateless comme un jeton JWT stocké dans le “session storage” HTML5 quand vous en avez la possibilité)</li><li style="text-align: justify;"><a href="http://symfony.com/doc/current/cookbook/email/email.html">envoyer des e-mails</a> (Swift Mailer) ;</li><li style="text-align: justify;"><a href="http://symfony.com/doc/current/cookbook/configuration/web_server_configuration.html">utiliser Apache ou Nginx</a>, et même <a href="https://dunglas.fr/2015/07/deploying-symfony-and-api-platform-apps-on-heroku-easily/">Heroku</a>.</li></ul>

API Platform (beta) : le framework web PHP nouvelle génération (partie 2)

Nous venons de publier un nouveau bundle Open Source : <a href="https://github.com/coopTilleuls/CoopTilleulsOvhBundle" target="_blank" rel="noopener">CoopTilleulsOVHBundle</a>.



Ce bundle intègre le kit de développement PHP fourni par OVH et l&rsquo;expose comme un service Symfony. Il fournit également un moyen pratique de stockage des informations d&rsquo;identification de l&rsquo;API dans le fichier&nbsp;



<code>parameters.yml.</code>



L&rsquo;API OVH dispose&nbsp;un&nbsp;grand nombre de fonctionnalités incluant&nbsp;le management dynamique et le monitoring des serveurs, l&rsquo;envoi des sms, la configuration du système de téléphonie, la facturation&#8230; Presque tous les services fournis par le leader européen de l&rsquo;hébergement web sont exposés à travers leur API et peuvent désormais être utilisés depuis n&rsquo;importe quelle application Symfony.



Le code source et les textes sont disponibles sur notre compte <a href="https://github.com/coopTilleuls/CoopTilleulsOvhBundle" target="_blank" rel="noopener">Github</a>. Le bundle peut être installé en utilisant Composer. Retrouvez <a href="http://dunglas.fr/2014/12/cooptilleulsovhbundle-ovh-sdk-integration-in-symfony/" target="_blank" rel="noopener">la version anglaise</a> de cet article&nbsp;!

Utiliser l'API OVH depuis Symfony grâce à CoopTilleulsOVHBundle

Installer phpDocumentator

# apt-get install graphviz php5-intl # phpDocumentator dependencies # su jenkins $ cd $ wget http://phpdoc.org/phpDocumentor.phar

Test d'acceptation avec Behat et PhantomJS

&amp;lt;?php// Adapted from https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Resources/config/router_prod.phpif (is_file($_SERVER['DOCUMENT_ROOT'].DIRECTORY_SEPARATOR.$_SERVER['SCRIPT_NAME'])) {
    return false;
}$_SERVER = array_merge($_SERVER, $_ENV);
$_SERVER['SCRIPT_FILENAME'] = $_SERVER['DOCUMENT_ROOT'].DIRECTORY_SEPARATOR.'app_test.php';require 'app_test.php';

# su jenkins
$ cd
$ wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.8-linux-x86_64.tar.bz2
$ tar xvjpf phantomjs-1.9.8-linux-x86_64.tar.bz2&lt;/pre>
&lt;p style="text-align: justify;">Les fichier &lt;em>behat.yml&amp;nbsp;&lt;/em>de votre projet doit être changé pour spécifier l'URL de base et l'hôte&amp;nbsp;Webdriver de Selenium 2 à utiliser. Voici un fichier d'exemple :&lt;/p>
&lt;div id="crayon-54b8cf0286437076090674" class="print-yes notranslate" style="text-align: justify;" data-settings=" minimize scroll-mouseover">
&lt;div class="crayon-plain-wrap">
&lt;pre class="lang:default decode:true">default:
    extensions:
        BehatMinkExtension:
            base_url: "http://127.0.0.1:8000"
            selenium2:
                wd_host: "http://127.0.0.1:8787/wd/hub"

V&eacute;rifier la qualit&eacute; du code avec&nbsp;SensioLabs Insight

# su jenkins
$ cd
$ wget http://get.insight.sensiolabs.com/insight.phar

Le D&eacute;ploiement Continu avec Capifony

# apt-get install rubygems
# gem install capifony

Cr&eacute;er le projet Jenkins

ghRepo=myOrg/myRepo
ghAccessToken=MyGitHubAccessToken
insightProject=my-sensiolabs-insight-project-uuidecho '{"state":"pending", "target_url": "'$BUILD_URL'", "description": "Build in progress..."}' | curl --header "Content-Type: application/json" -d @- https://api.github.com/repos/$ghRepo/statuses/$GIT_COMMIT?access_token=$ghAccessToken# Rebuild Satis index
~/satis/bin/satis --no-interaction build ~/packages.json ~/packages# Cleanup parameters.yml file from previous builds, we will let Symfony generate a new file with the default settings
if [ -f "app/config/parameters.yml" ]; then
  rm app/config/parameters.yml
fi# Cleanup cache from previous builds
if [ -d "app/cache" ]; then
  rm -Rf app/cache/*
fi# Create a build directory if necessary
mkdir -p build# To collect commands statutes
status=0# Analyze with SL Insight
php ~/insight.phar analyze $insightProject
# Check the result if the result is a platinum medal (all is good)
# Fail conditions are customizable, see http://blog.insight.sensiolabs.com/2014/02/12/jenkins-integration.html
php ~/insight.phar analysis $insightProject --format="pmd" --fail-condition="analysis.getGrade() != 'platinum'" &amp;gt; build/pmd.xml || status=$((status+$?))# Check CS
php ~/php-cs-fixer.phar fix --no-interaction --dry-run --diff -vvv src/ || status=$((status+$?))# Generate PHPDoc
php ~/phpDocumentor.phar -d src -t build/doc || status=$((status+$?))# Install dependencies through Composer
php ~/composer.phar install --no-interaction --dev || status=$((status+$?))# Create the database (I mostly use a SQLite database stored in the cache/ directory of the app)
php app/console -e=test doctrine:schema:create || status=$((status+$?))# Load fixtures
php app/console -e=test doctrine:fixtures:load || status=$((status+$?))# Run unit tests through phpspec and store the result in the JUnit format, we will use it later
bin/phpspec run --format junit &amp;gt; build/unit.xml || status=$((status+$?))# If you use phpunit instead of phpspec, comment the previous and uncomment the following line
#./bin/phpunit --log-junit build/unit.xml || status=$((status+$?))# Run PHP built-in web server
# Use the dev router because no test router is provided by default
php app/console server:run -e=test --router=app/config/router_test.php &amp;amp;# Store the PID of the process in a variable
serverPID=$!# Run PhantomJS in WebDriver mode (Selenium2)
~/phantomjs-1.9.8-linux-x86_64/bin/phantomjs --webdriver=8787 &amp;amp;# Store the PID again
phantomPID=$!# Wait for HTTP server and PhantomJS initialization
sleep 30# Run Behat scenarios
# The result is send to the console because the jUnit formatter is not ready yet for Behat 3.0 (https://github.com/Behat/Behat/issues/358)
bin/behat || status=$((status+$?))# Stop the HTTP server and PhantomJS
kill -9 $serverPID
kill -9 $phantomPIDif [ $status -eq 0 ]; then
    # Update the commit status on success
    echo '{"state":"success", "target_url": "'$BUILD_URL'", "description": "The build succeeded!"}' | curl --header "Content-Type: application/json" -d @- https://api.github.com/repos/$ghRepo/statuses/$GIT_COMMIT?access_token=$ghAccessToken    # Continuous deployment
    cap deploy
else
    # Update commit status on failure
    echo '{"state":"failure", "target_url": "'$BUILD_URL'", "description": "The build failed."}' | curl --header "Content-Type: application/json" -d @- https://api.github.com/repos/$ghRepo/statuses/$GIT_COMMIT?access_token=$ghAccessToken
fi# Return build status
exit $status

R&eacute;soudre les probl&egrave;mes de limites d'utilisation de l'API GitHub

# su jenkins
$ php composer.phar create-project dunglas/php-schema.org-model
Username: my-machine-user
Password: my-password

R&eacute;soudre les probl&egrave;mes de mails

Mettre &agrave; jour automatiquement les outils install&eacute;s localement&nbsp;

#!/bin/sh
php composer.phar self-update
php php-cs-fixer.phar self-update
# The self-update option of phpDocumentator is broken at time of writing
wget -q http://phpdoc.org/phpDocumentor.phar -O phpDocumentor.phar
cd satis/
php ../composer.phar update --no-interaction

Connecter Jenkins aux d&eacute;p&ocirc;ts Github

Autoriser Git et support de GitHub

Chaîne d'intégration continue pour les applications Symfony

Cosmocover, l&rsquo;agence de marketing lilloise spécialisée dans les jeux vidéos, a confié à Les-Tilleuls.coop le développement de son nouveau site internet. Il est basé sur le populaire CMS open source <a href="http://fr.wordpress.org/" target="_blank" rel="noopener">WordPress</a>. <a href="http://www.cosmocover.com/">Découvrez-le</a> dès maintenant ! &nbsp;

# app/config/config.yml
coop_tilleuls_ymlp:
  # YMLP URL for API calls (default to https://www.ymlp.com/api/)
  api_url: https://www.ymlp.com/api/
  # Your YMLP API key (no default)
  api_key: YOURSECRETAPIKEY1234
  # Your YMLP username (no default)
  api_username: tilleuls

use CoopTilleulsBundleYmlpBundleYmlpExceptionYmlpException;
// Get an instance of the YMLP API client as a service
$ymlpClient = $this->get('coop_tilleuls_ymlp.client');// Call the simple Ping() command of the YMLP API
$pingResponse = $ymlpClient->call('Ping');// Add a new contact to one or more groups with exception handling
try {
    $contactsAddResponse = $ymlpClient->call('Contacts.Add', array('Email' => 'baptiste@les-tilleuls.coop', 'GroupID' => 1));
} catch (YmlpException $e) {
    //...
}

<h1 class="p1">L&rsquo;e-mailing ou marketing par e-mail</h1>



Il existe aujourd’hui de nombreuses façons de faire la promotion de produits ou de faire passer des messages auprès d’utilisateurs ciblés sur le web. L’une d’elle s’appelle l’e-mailing, une technique de marketing direct par voie de courriers électroniques. L’e-mailing, ou marketing par e-mail, offre de nombreux avantages. Il est rapide et efficace, facile à mettre en place, il offre une liberté graphique, il permet de cibler son public, d’analyser l’impact de ses retours et surtout, son coût est modique.



Un nombre important de solutions est apparu afin de le mettre en oeuvre. Parmi les plus connues et courantes, on retrouve <a title="MailChimp" href="http://mailchimp.com/" target="_blank" rel="nofollow noopener">MailChimp</a>, <a title="Sarbacane" href="http://www.sarbacane.com/" target="_blank" rel="nofollow noopener">Sarbacane</a> ou encore <a title="YMLP" href="https://www.ymlp.com/fr/" target="_blank" rel="nofollow noopener">YMLP (YourMailingListProvider)</a>.



Chez Les-Tilleuls.coop, nous sommes&nbsp;régulièrement sollicités et sommes&nbsp;en mesure de <a title="Services" href="https://les-tilleuls.coop/services/">répondre à vos différents besoins</a> en terme de création graphique et intégration, responsive ou non,&nbsp;de templates pour des campagnes d’e-mailing, de rédaction de leurs contenus ou encore d’intégration des différentes solutions dans des développements.



<h1 class="p1">L&rsquo;API YMLP</h1>



Pour les besoins d’un projet <a title="Symfony2" href="http://symfony.com/" target="_blank" rel="nofollow noopener">Symfony2</a> récent, nous avons dû intégrer à notre application les services du fournisseur de mailing pour professionnels, <a title="YMLP" href="http://www.ymlp.com/fr/" target="_blank" rel="nofollow noopener">YMLP (YourMailingListProvider)</a>.



YMLP fournit pour cela une API plutôt bien garnie en commandes, <a title="YMLP API" href="http://www.ymlp.com/app/api.php" target="_blank" rel="nofollow noopener">et, qui plus est, bien documentée (sous réserve d’avoir des identifiants)</a>, couvrant une grande partie des fonctionnalités disponibles sur l’interface web.



<h1 class="p1">CoopTilleulsYmlpBundle pour Symfony2</h1>



De par <a title="Projet social" href="https://les-tilleuls.coop/projet-social/">nos valeurs</a>&nbsp;communes et <a title="Open Source" href="https://les-tilleuls.coop/produits/open-source/">notre implication</a> au sein de Les-Tilleuls.coop pour les logiciels libres, nous avons décidé de partager aujourd’hui avec la communauté le fruit de notre travail sous <a title="Licence MIT" href="http://opensource.org/licenses/MIT" target="_blank" rel="nofollow noopener">licence MIT</a>, à savoir le développement d’un client, sous forme de <a title="Symfony2 bundles" href="http://symfony.com/fr/doc/current/cookbook/bundles/index.html" target="_blank" rel="nofollow noopener">bundle Symfony2</a>, pour l’API d’YMLP : <a title="CoopTilleulsYmlpBundle v1.0.0" href="https://github.com/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle v1.0.0</a>.



Ce bundle utilise la librairie <a title="Guzzle 4" href="https://github.com/guzzle/guzzle" target="_blank" rel="nofollow noopener">Guzzle 4</a> qui requière donc PHP &gt;= 5.4. Votre projet doit également utiliser Symfony dans ses versions &gt;= 2.2.



A noter que vous n’êtes pas obligés d’utiliser Symfony2 sous sa forme framework full-stack puisque ce bundle ne dépend que de 3 composants de celui-ci, à savoir <a title="Config" href="http://symfony.com/fr/doc/current/components/config/index.html" target="_blank" rel="nofollow noopener">Config</a>, <a title="Dependency Injection" href="http://symfony.com/fr/doc/current/components/dependency_injection/index.html" target="_blank" rel="nofollow noopener">Dependency Injection</a> et <a title="HttpKernel" href="HttpKernel" target="_blank" rel="nofollow noopener">HttpKernel</a>.



Ce bundle a été <a title="Travis" href="https://travis-ci.org/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">entièrement testé</a> avec <a title="PHPSpec" href="http://www.phpspec.net/" target="_blank" rel="nofollow noopener">PHPSpec</a> et a obtenu la <a title="Platinum medal" href="https://insight.sensiolabs.com/projects/5be76419-0b77-4283-82c9-7333dcf43595" target="_blank" rel="nofollow noopener">médaille de platine</a> sur le nouvel outil d’analyse et d’évaluation de la qualité des projets PHP, <a title="Nouveau sfPot à Lille : conférence de Fabien Potencier" href="https://les-tilleuls.coop/nouveau-sfpot-a-lille-conference-de-fabien-potencier/">Sensiolabs Insight</a>.



<h2 class="p1">Installation</h2>



L’installation se fait très simplement à partir de <a title="Composer" href="https://getcomposer.org/" target="_blank" rel="nofollow noopener">Composer</a> :





Il vous suffit alors d’ajouter le bundle au noyau de l’application :





<h2 class="p1">Configuration</h2>



La première étape de la configuration se passe sur l’interface web d’YMLP, <a title="API YMLP" href="http://www.ymlp.com/app/api.php" target="_blank" rel="nofollow noopener">dans l’onglet configuration puis le sous-onglet API</a>. Il vous faut activer l’accès à l’API que vous pouvez aussi restreindre à certaines adresses ou plages d’adresses IP. Enregistrez vos changements, une clé API sera alors générée.



<figure class="wp-block-image"><a href="https://les-tilleuls.coop/wp-content/uploads/2014/07/ymlp-config.png"><img src="https://les-tilleuls.coop/wp-content/uploads/2014/07/ymlp-config-780x354.png" alt="ymlp-config" class="wp-image-1872"/></a></figure>







Dans le fichier de configuration de votre application Symfony2, ajoutez les entrées suivantes :





<h2 class="p1">Utilisation</h2>



Le client est maintenant configuré et prêt à l’emploi. Voici un exemple d’utilisation :





La méthode&nbsp;<code>call()</code>&nbsp;retourne un tableau contenant la réponse de l&rsquo;API ou déclenche une exception de type&nbsp;<code>CoopTilleulsBundleYmlpBundleYmlpExceptionYmlpException</code>.



<h2 class="p1">Liens</h2>



<ul><li><a href="http://github.com/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle sur Github</a></li><li><a href="https://packagist.org/packages/tilleuls/ymlp-bundle" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle sur Packagist</a></li><li><a href="http://knpbundles.com/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle sur KnpBundles</a></li><li><a href="https://travis-ci.org/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle sur Travis</a></li><li><a href="https://insight.sensiolabs.com/projects/5be76419-0b77-4283-82c9-7333dcf43595" target="_blank" rel="nofollow noopener">CoopTilleulsYmlpBundle sur Sensiolabs Insight</a></li></ul>



Vous pouvez également retrouver cette documentation sur le <a title="CoopTilleulsYmlpBundle" href="https://github.com/coopTilleuls/CoopTilleulsYmlpBundle" target="_blank" rel="nofollow noopener">dépôt Github</a>. N’hésitez pas à apporter vos contributions au projet ! Bon e-mailing. 🙂