Comment faire une API REST vite fait bien fait avec API-Platform 2. Présentation de 20min à l'AFUP de Montpellier, le 04/10/2018

1. Guilhem Bourgoin Développeur Symfony Freelance
Une API REST vite fait bien
fait avec API-Platform 2

2. Introduction

3. API : Application Programming Interface
=> Point d’entrée permettant à un logiciel d’offrir des services à d'autres logiciels.
REST : Representational State Transfer
=> Chaque ressource doit avoir un identifiant unique (URI).
=> Utilisation du protocole HTTP pour la manipulation des ressources.
=> Les ressources doivent être liées les unes aux autres par des liens.
API REST ?

4. Installation et configuration

5. Installation
1 composer create-project symfony/skeleton:4.1.* api-demo
cd api-demo/
composer req api
.env :
DATABASE_URL=mysql://root@127.0.0.1:3306/api-demo
php bin/console doctrine:database:create
2
3
4

6. namespace AppEntity;
use ApiPlatformCoreAnnotationApiResource;
use DoctrineORMMapping as ORM;
/**
* @ApiResource
* @ORMEntity
*/
class Book
{
/**
* @ORMId
* @ORMColumn(type="integer")
* @ORMGeneratedValue(strategy="AUTO")
*/
private $id;
/**
* @ORMColumn(type="string", length=255)
*/
private $title;
/**
* @ORMManyToOne(targetEntity="Editor", inversedBy="books")
* @ORMJoinColumn(nullable=false)
*/
private $editor;
Entity Book

7. use ApiPlatformCoreAnnotationApiResource;
/**
* @ApiResource
* @ORMEntity
*/
class Editor
{
/**
* [...]
*/
private $id;
/**
* @ORMColumn(type="string", length=255)
*/
private $name;
/**
* @ORMOneToMany(targetEntity="Book", mappedBy="editor")
*/
private $books;
public function __construct()
{
$this->books = new ArrayCollection();
}
Entity Editor

8. php bin/console doctrine:schema:update --force

9. Paramétrages

10. Paramétrage - Validation
/**
* @ORMColumn(type="string", length=255, nullable=false)
* @AssertNotBlank
* @AssertLength(max=255)
*/
private $title;
/**
* @ORMManyToOne(targetEntity="Editor", inversedBy="books")
* @ORMJoinColumn(nullable=false)
* @AssertNotNull
*/
private $editor;

11. Paramétrage - Validation

12. Paramétrage - filtres de recherche
/api/books?title=martine
/api/books?editor.name=Galimard
/api/books?editor.name=Galimard&title=martine
/**
* @ApiResource
* @ApiFilter(SearchFilter::class, properties={
* "title": "partial",
* "editor.name": "exact"
* })
* @ORMEntity
*/
class Book

13. Paramétrage - filtres de recherche
Search Filter
?property=value
exact - partial - start - end - word_start
Numeric Filter
Boolean Filter
Range Filter
Exists Filter
Order Filter
Custom Filter
Date Filter
?property[<after|before|strictly_after|strictly_before>]=value

14. Paramétrage - Opérations
/**
* @ApiResource(
* collectionOperations={"get"},
* itemOperations={"get"}
* )
* @ORMEntity
*/
class Book

15. Paramétrage - Sous ressources
/**
* @ApiResource
* @ORMEntity
*/
class Editor
{
[...]
/**
* @ORMOneToMany(targetEntity="Book", mappedBy="editor")
* @ApiSubresource
*/
private $books;

16. Paramétrage
Sérialization
/**
* @ApiResource(
* normalizationContext={"groups"={"book_read"}},
* denormalizationContext={"groups"={"book_write"}}
* )
* @ORMEntity
*/
class Book
{
/**
* @Groups({"book_read"})
*/
private $id;
/**
* @Groups({"book_read", "book_write"})
*/
private $title;
/**
* @Groups({"book_read", "book_write"})
*/
private $editor;

17. Paramétrage - Sérialization, lecture
normalizationContext={"groups"={"book_read"}}
{
"id": 1,
"title": "Da Vinci Code",
"editor": "/api/editors/1"
}
normalizationContext={"groups"={"book_read", "editor_read"}}
{
"id": 1,
"title": "Da Vinci Code",
"editor": {
"id": 1,
"name": "Gallimard"
}
}

18. Paramétrage - format de communication

19. Les évènements

21. Pour aller plus loin

22. Filtres par défaut
Pagination des listes
Format custom
FOS User Bundle integration
Authentification JWT
Gestion des rôles
Pour aller plus loin
FetchEager
Behat et Behatch
Documentation Swagger / Nelmio
GraphQL support
Schema.org
Back Office en React

23. Conclusion
+
Rapide et facile à mettre en place
Souple et paramétrable
Communauté active
Préconisé par SensioLabs
-
Quelques bugs
Doc relativement peu à jour

25. Guilhem Bourgoin Développeur Symfony Freelance
Merci :)
A vos questions !

26. Annexes

28. JSON for Linked Data
=> Développé par Google.
=> Recommandé par le W3C depuis 2014.
=> JSON Standard avec des clés spéciales pour décrire le contexte
=> Compatible avec les technologies existantes
JSON-LD
{
"@context": "/api/contexts/Book",
"@id": "/api/books/1",
"@type": "Book",
"id": 1,
"title": "Da Vinci Code",
"editor": "/api/editors/1"
}