Concevoir son API pour le futur

Transcript

1. Concevoir son API pour le futur Inspirations de Symfony Titouan Galopin
2. Titouan Galopin Symfony Core Team member (Symfony UX) Tech Lead 2
3. Introduction 3 Notre challenge à Selency
4. Agenda • De quoi parle-t-on ? • Déconnecter l’interne de l’externe • Communiquer le changement • Documenter pour expliquer 4
5. 1. De quoi parle-t-on ? Quelles sont les difficultés dans la conception d’une API moderne ?
6. 6 Une API est un contrat
7. 7 Des consommateurs (Web, mobile, desktop, autres API, …) dépendent de notre API
8. 8 Différentes personnes travaillent autour de ce contrat
9. 9 Concevoir une API ~= Concevoir une librairie PHP réutilisable
10. 10 • Rester stable dans le temps • Créer des chemins de migration • Communiquer aux consommateurs
11. 11 On a de la chance : Symfony a déjà créé ces processus ! Et si on les réutilisait ?
12. 2. Déconnecter l’interne de l’externe Ne pas exposer le format interne de données
13. 13 Être stable => Découpler les inputs/output API de la logique interne
14. 14 Output Les transformers
15. 15 Pas de serializer automatique ! Si l’entité change, l’output ne doit pas changer
16. 16 Transformer = Serializer manuel + Sous-ressources Exemple : League Fractal https://fractal.thephpleague.com (=> nous avons notre propre système à Selency)
17. 17 Base de données Controller & Entité Transformer Output API
18. 18 Base de données Controller & Entité Transformer Output API Si le code change dans le controller ou l’entité, le transformer permet de garder le même output
19. 19 class BookTransformer extends Fractal\TransformerAbstract { public function transform(Book $book) { return [ 'id' => (int) $book->getId(), 'title' => $book->getTitle(), 'year' => (int) $book->getYear(), 'links' => [ [ 'rel' => 'self', 'uri' => '/books/'.$book->getId(), ] ], ]; } }
20. 20 class BookTransformer extends Fractal\TransformerAbstract { public function transform(Book $book) { return [ 'id' => (int) $book->getId(), 'title' => $book->getTitle(), 'year' => (int) $book->getYear(), 'links' => [ [ 'rel' => 'self', 'uri' => '/books/'.$book->getId(), ] ], ]; } }
21. 21 Les transformers permettent aussi de gérer les links, sous-ressources, … => cf. League Fractal
22. 22 Input Utilisez des Data Transfer Object
23. 23 Pas de deserializer directement dans l’entité ! Risques : si l’entité change => incompatibilité si input invalide => entité invalide + TypeError si propriété typée
24. 24 Input API DTO Controller & Entité Base de données Utilisez des DTO dédiés
25. 25 Input API DTO Controller & Entité Base de données Si le code change dans le controller ou l’entité, le DTO permet de garder le même input Utilisez des DTO dédiés
26. 26 class AuthRegisterPayload { #[Assert\Email(mode: Email::VALIDATION_MODE_STRICT)] #[Assert\NotBlank] public $email; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $firstName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $lastName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $password; }
27. 27 class AuthRegisterPayload { #[Assert\Email(mode: Email::VALIDATION_MODE_STRICT)] #[Assert\NotBlank] public $email; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $firstName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $lastName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $password; }
28. 28 $payload = $this->serializer->deserialize( data: $request->getContent(), type: AuthRegisterPayload::class, format: 'json' ); $errors = $this->validator->validate($payload); if ($errors->count() > 0) { throw new PayloadValidationException($errors); }
29. 29 Bonus : pas d’entités anémiques
30. 30 $user = new User(); $user->setEmail($email); $user->setFirstName($firstName); $user->setLastName($lastName); $user->setPassword($hashedPassword); Entité anémique : difficile à maintenir
31. 31 $user = new User(); $user->setEmail($email); $user->setFirstName($firstName); $user->setLastName($lastName); $user->setPassword($hashedPassword); Entité anémique : difficile à maintenir $user n’est initialement pas valide
32. 32 $user = new User(); $user->setEmail($email); $user->setFirstName($firstName); $user->setLastName($lastName); $user->setPassword($hashedPassword); Entité anémique : difficile à maintenir $user n’est initialement pas valide Est-ce qu’on est sûr qu’on update bien tous les bons champs ?
33. 33 class User { public static function createFromPayload(AuthRegisterPayload $payload): self { // ... } public function applyUpdatePayload(UserUpdatePayload $payload) { // ... } } A la place, payloads + entités riches
34. 34 // RegistrationController $payload = $this->createPayload($request->getContent(), AuthRegisterPayload::class); $user = User::createFromPayload($payload); // UpdateController $payload = $this->createPayload($request->getContent(), UserUpdatePayload::class); $user->applyUpdatePayload($payload); A la place, payloads + entités riches
35. 3. Communiquer sur le changement Versionner et déprécier
36. 36 Une fois qu’on a découplé l’interne de l’externe, on peut adopter des processus de gestion du changement
37. 37 API Semantic Versionning Versionner l’input/output de l’API
38. 38 Techniques de versionning Host : https://v1-1.api.selency.com/users Path prefix : https://api.selency.com/v1.1/users Header : Accept: application/vnd.selency.v1.1+json
39. 39 Majeure . Mineure . Patch Incompatibilité I/O Bugfix compatible I/O Feature compatible I/O
40. 40 Compatibilité en input Ajouter un champ requis ❌ Ajouter un champ optionnel ✅ Renommer un champ ❌ Supprimer (ignorer) un champ ✅ Compatibilité en output Ajouter un champ ✅ Renommer un champ ❌ Supprimer un champ ❌
41. 41 Gérer plusieurs versions d’API dans le même projet => un transformer/DTO par version majeure
42. 42 class V1\BookTransformer { public function transform(Book $book) { return [ 'id' => $book->getId(), 'title' => $book->getTitle(), 'year' => $book->getYear(), ]; } } class V2\BookTransformer { public function transform(Book $book) { return [ 'id' => $book->getId(), 'title' => $book->getTitle(), 'date' => $book->getDate(), ]; } }
43. 43 class V1\AuthRegisterPayload { #[Assert\NotBlank] public $email; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $password; } class V2\AuthRegisterPayload { #[Assert\NotBlank] public $email; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $firstName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $lastName; #[Assert\Type(type: 'string')] #[Assert\NotBlank] public $password; }
44. 44 Le versionning rend indépendant le calendrier des consommateurs de celui de l’API => stabilité, fiabilité, confiance
45. 45 Créer des chemins de migration grâce aux dépréciations
46. 46 Chemin de migration en input Ajouter/Renommer un champ requis 1. Ajout du nouveau champ en optionnel 2. Dépréciation du précédent champ (si applicable) 3. Utilisation priorisée nouveau > ancien 4. Prochaine majeure : suppression ancien champ
47. 47 Chemin de migration en output Renommer un champ 1. Ajout du nouveau nom de champ (même valeur) 2. Dépréciation du précédent nom 3. Prochaine majeure : suppression ancien champ
48. 48 Chemin de migration en output Supprimer un champ 1. Dépréciation 2. Prochaine majeure : suppression ancien champ
49. 4. Documenter pour expliquer Expliquer le pourquoi et le comment
50. 50 Versionner sans communiquer est inutile Il faut un moyen de communiquer aux consomateurs
51. 51 OpenAPI Standard de documentation API Gère très bien les dépréciations Standard => clients, viewers, …
52. 52 Selency OpenAPI Notre librairie de création de doc OpenApi : https://github.com/selency/openapi Permet d’associer la documentation aux transformers + payloads
53. 53 class AuthRegisterPayload implements SelfDescribingSchemaInterface { // ... public static function describeSchema($schema, $openApi): void { $schema ->required(['email', 'firstName', 'lastName', 'password']) ->property('email', $openApi->schema() ->type('string') ->example('john.doe@domain.com') ) ->property('firstName', $openApi->schema() ->type('string') ->example('John') ) ->property('lastName', $openApi->schema() ->type('string') ->example('Doe') ) ->property('password', $openApi->schema() ->type('string') ->description('Plain text password') ) ; } }
54. 54 class AuthRegisterPayload implements SelfDescribingSchemaInterface { // ... public static function describeSchema($schema, $openApi): void { $schema ->required(['email', 'firstName', 'lastName', 'password']) ->property('email', $openApi->schema() ->type('string') ->example('john.doe@domain.com') ) ->property('firstName', $openApi->schema() ->type('string') ->example('John') ) ->property('lastName', $openApi->schema() ->type('string') ->example('Doe') ->deprecated(true) ) ->property('password', $openApi->schema() ->type('string') ->description('Plain text password') ) ; } }
55. 55 // openapi/V2/Documentation.php $doc->path('/auth/register', $this->openApi->pathItem() ->post($this->openApi->apiOperation() ->tag('Auth') ->operationId('app.auth.register') ->summary('Register') ->description('Create a user, return a user token') ->securityRequirement(null) ->requestBody($this->openApi ->requestBody() ->required(true) ->content('application/json', AuthRegisterPayload::class) ) ->responses($this->openApi->responses() ->response('200', $this->openApi->response() ->description('Return the token of the new user') ->content('application/json', AuthTokenTransformer::class) ) ) ) );
56. 56 // openapi/V2/Documentation.php $doc->path('/auth/register', $this->openApi->pathItem() ->post($this->openApi->apiOperation() ->tag('Auth') ->operationId('app.auth.register') ->summary('Register') ->description('Create a user, return a user token') ->securityRequirement(null) ->requestBody($this->openApi ->requestBody() ->required(true) ->content('application/json', AuthRegisterPayload::class) ) ->responses($this->openApi->responses() ->response('200', $this->openApi->response() ->description('Return the token of the new user') ->content('application/json', AuthTokenTransformer::class) ) ) ) );
57. Conclusion • Déconnecter l’interne de l’externe • Communiquer le changement • Documenter pour expliquer 57
58. 58 Merci ! Des questions ? Retrouvez moi sur : ◦ Twitter @titouangalopin // GitHub @tgalopin ◦ galopintitouan@gmail.com Design by slidescarnival.com