API Platform: The Pragmatic API framework

API Platform 4.0 got released. Discover Pragmatic API development with API Platform.

1. The pragmatic API framework API PLATFORM CON 2024 - LILLE, FRANCE & ONLINE

2. API PLATFORM CON 2023 - LILLE, FRANCE & ONLINE API PLATFORM 4

3. About Me API Platform release manager CTO at Les-Tilleuls.coop Developer, biker, builder Recent father Antoine Bluchet soyuka @phpc.social @s0yuka soyuka .me

4. with API Platform Pragmatic API development

5. Pragmatic API development Enable (or disable) the features you (don’t) need Decorate our extension points (IRI Converter, providers , processors, etc. ) API Platform segregates commands and queries It’s not always CRUD: u se operations to create RPC endpoints Don’t fight the framework

6. Enable / Disable Features use ApiPlatform\Metadata\Post; #[ Post ( read : true , // to call the provider write : true , // to call the processor deserialize : false , // transforms the request body to this resource's class serialize : false , // transforms the provider's response to JSON validate : false , // validates the user input queryParameterValidationEnabled : false , // validates query parameters output : false , // using false will return nothing openapi : false , // disables the OpenAPI documentation )] class Book {}

7. use ApiPlatform\Metadata\ApiResource; use App\State\BookProvider; #[ Put ( uriTemplate : '/books/{id}' , allowCreate : true , // create a new value through a PUT operation provider : BookProvider :: class , processor : BookProcessor :: class , )] class Book { } State Provider / Processor

8. use ApiPlatform\Metadata\Operation; use ApiPlatform\State\ProviderInterface; use ApiPlatform\Laravel\Eloquent\State\ItemProvider; use ApiPlatform\Doctrine\Orm\State\ItemProvider; final readonly class BookProvider implements ProviderInterface { public function __construct( private ItemProvider $itemProvider ) {} public function provide( Operation $operation , array $uriVariables = [], array $context … { return $this -> itemProvider ->provide( $operation , $uriVariables , $context ); } } Decorate the state providers

9. use ApiPlatform\Metadata\Operation; use ApiPlatform\State\ProviderInterface; final class BookProvider implements ProviderInterface { public function provide( Operation $operation , array $uriVariables = [], array $context … { $dbh = new \ PDO ( 'sqlite:/db.sqlite' ); $sth = $dbh ->prepare( 'SELECT * FROM book WHERE id = :id' ); $sth ->bindParam( 'id' , $uriVariables [ 'id' ], \ PDO :: PARAM_STR ); $sth ->execute(); return !( $result = $sth ->fetch()) ? null : $result ; } } Any data source

10. use ApiPlatform\Metadata\Operation; use ApiPlatform\State\ProviderInterface; final class BookProvider implements ProviderInterface { public function provide( Operation $operation , array $uriVariables = [], array $context … { return json_decode( file_get_contents( 'https://demo.api-platform.com/api/books.jsonld' ) ); } } Any data source

11. Use your favorite query builder use ApiPlatform\Laravel\Eloquent\State\Options; use Illuminate\Database\Eloquent\Builder; #[ GetCollection ( uriTemplate : '/author/{author}/books' , uriVariables : [ 'author' ], stateOptions : new Options ( handleLinks : [ self :: class , 'handleLinks' ] ) )] class Employee { public static function handleLinks( Builder $builder , array $uriVariables , array $context ): Builder { $builder ->where( 'books.author_id' , $uriVariables [ 'author' ]); } } AVAILABLE FOR Doctrine ORM Doctrine ODM Laravel Eloquent Elasticsearch ESQL

12. use ApiPlatform\Metadata\Post; #[ Post ( uriTemplate : '/rpc' , processor : [ self :: class , 'process' ])] final readonly class PostContent { public function __construct( public string $name ) {} public static function process( mixed $data ) { // do something with $data } } RPC endpoints

13. Not convinced?

14. Why you should use API Platform commit f55cfce9c014655dd5343a5f20dfaf9ec5df2da0 Author: Kévin Dunglas < dunglas @ gmail . com > Date: Tue Jan 20 00:16:57 2015 + 0100 first commit REST oriented JSON-LD , JSON:API serialization OpenAPI, Hydra, JSON Schema documentation URI based mechanics (cache, live updates, relations etc.) Embedded content negotiation, validation and authorization 10 years of existence in January

15. The power of Edge Side APIs

16. 1 2 3 4 5 Atomic Resource Pre-generate HTTP Cache Preload Push edge-side-api.rocks

17. Embedding...

18. @api-platform/ld { "@id" : "/books/1" , "@type" : [ "https://schema.org/Book" ], "title" : "Hyperion" , "author" : "https://localhost/authors/1" } fetch ( ' /books/1 ' )

19. @api-platform/ld { "@id" : "/books/1" , "@type" : [ "https://schema.org/Book" ], "title" : "Hyperion" , "author" : " https://localhost/authors/1 " } fetch ( ' /authors/1 ' )

20. @api-platform/ld { "@id" : "/books/1" , "@type" : [ "https://schema.org/Book" ], "title" : "Hyperion" , "author" : " https://localhost/authors/1 " } fetch ( ' /authors/1 ' )

21. @api-platform/ld { "@id" : "/books/1" , "@type" : [ "https://schema.org/Book" ], "title" : "Hyperion" , "author" : " https://localhost/authors/1 " } import ld from '@api-platform/ld' await ld( '/books' , { urlPattern : new URLPattern ( "/authors/:id" , "https://localhost" ) }) console .log(books.author?.name)

22. @api-platform/mercure import mercure, { close } from "@api-platform/mercure" ; await mercure( 'https://localhost/authors/1' , { onUpdate: (author) => console .log(author) }) Link: </.well-known/mercure>; rel="mercure"

23. Mercure Resource live updates Compatible with Laravel Echo High Availability as a service https://mercure.rocks

24. @api-platform/ld + @api-platform/mercure const fetchFn = (url) => { return mercure(url).then(d => d.json()) } ld( '/books' , { fetchFn : fetchFn, urlPattern : pattern }) .then(books => { // Do something with books })

25. Client tools Admin generator @api-platform/admin Manage topics on a single EventSource connection @api-platform/mercure Replace fetch by @api-platform/ld for linked data And more at api-platform.com

26. Atomic resources? Small and atomic documents Don’t embed resources, use URIs instead Better browser and share cache hit rate Clients fetch only what they initially need and update only small chunks of data Hypermedia is at the heart of Edge Side APIs (JSON-LD, Hydra, JSON:API) Read our white paper !

27. IRIs collection GET /books Content-Type : application/ld+json { "@context" : "/contexts/Book" , "@id" : "/books" , "@type" : "Collection" , "totalItems" : 4 , "member" : [ "/books/1" , "/books/2" , "/books/3" , "/books/4" ] } GET / books Content - Type : application / ld + json { "@context" : "/contexts/Book" , "@id" : "/books" , "@type" : "Collection" , "totalItems" : 4 , "member" : [ { "@id" : "/books/1" , "title" : "API Platform" , "author" : "/authors/1" }, { "@id" : "/books/2" , ... }, ] }

28. use ApiPlatform\Metadata\ApiResource; #[ ApiResource ( normalizationContext : [ 'iri_only' => true ], )] final readonly class Book { } IRI Only GET /books Content-Type : application/ld+json { "@context" : "/contexts/Book" , "@id" : "/books" , "@type" : "Collection" , "totalItems" : 4 , "member" : [ "/books/73" , "/books/74" , "/books/75" , "/books/76" ] }

29. use ApiPlatform\Metadata\GetCollection; #[ ApiResource ( uriTemplate : ' /authors/{author}/books ' , uriVariables : [ 'author' => new Link ( fromClass : Author :: class , toProperty : 'author' ) ], normalizationContext : [ 'iri_only' => true ], )] final readonly class Book { } Group data with IRIs

30. use ApiPlatform\Metadata\ApiProperty; #[ ApiProperty ( property : 'books' , uriTemplate : '/authors/{author}/books' )] final readonly class Author { } GET /authors/1 Content-Type : application/ld+json { "@context" : "/contexts/Book" , "@id" : "/authors/1" , "@type" : "Author" , " books " : " /authors/1/books " } Group data with IRIs

31. Preload Preload resources Server push Early Hints Caddy module https://vulcain.rocks

32. API Platform 3.4/4.0 What’s new ?

33. Query parameters use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter; use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter; use ApiPlatform\Metadata\ApiResource; use ApiPlatform\Metadata\QueryParameter; #[ ApiResource ] #[ QueryParameter ( key : 'sort[:property]' , filter : OrderFilter :: class )] #[ QueryParameter ( key : ':property' , filter : PartialSearchFilter :: class )] class Book extends Model { }

34. Query parameters

35. Query parameters Header / Query parameter JSON Schema validation OpenAPI and Hydra compatible :property placeholder for better DX Better filter composition (OrFilter, decorate D octrine filters etc.) Filter aliasing

36. P arameters Header / Query parameter JSON Schema validation OpenAPI and Hydra compatible :property placeholder for better DX Better filter composition (OrFilter, decorate Doctrine filters etc.) Filter aliasing

37. Error management use ApiPlatform\Metadata\GetCollection; use App\Exception\MyDomainException; #[ GetCollection ( errors : [ MyDomainException :: class ])] class Book { }

38. Error management Exception can be API resources using ApiPlatform\Metadata\Error Specify errors in an operation to document them with OpenAPI Read our guides: api-platform.com/docs/guides/error-provider/ api-platform.com/docs/guides/error-resource/ Exception are automatically rendered using the Problem details specification (RFC 7807)!

39. Laravel support Most of our existing features are useable in a Laravel project Authorization and validation use Laravel FormRequest and policies Read the documentation: a pi-platform.com/docs/laravel/ Send feedbacks!

40. And way more… Doctrine ENUM filter Serializer default context fixes with an option to change the deserializer type Static headers Inflector is now a service Configure whether to override OpenAPI responses Read the CHANGELOG !

41. From v3 to v4 How to update?

42. $ composer require api-platform/core:^3.4 Update to API Platform 3.4 api-platform.com/docs/core/upgrade-guide/

43. FIX DEPRECATIONS!

44. $ composer update // composer.json - "api-platform/core": "^3.4", + "api-platform/symfony": "^3.4", + "api-platform/doctrine-orm": "^3.4", Step 1 Step 2 Step 3 $ phpunit Update to API Platform 3.4

45. api-platform/symfony Symfony API Platform integration api-platform/graphql Build GraphQL enpoints api-platform/laravel Laravel API Platform integration And more… Hydra, JSON-LD, OpenAPI, JSON Schema etc. api-platform/doctrine-orm Doctrine ORM bridge api-platform/doctrine-odm Doctrine ODM bridge Choose your components

46. api_platform: - use_symfony_listeners: true + use_symfony_listeners: false defaults: operations: - ApiPlatform\Metadata\Get - ApiPlatform\Metadata\GetCollection - ApiPlatform\Metadata\Post - - ApiPlatform\Metadata\Put - ApiPlatform\Metadata\Patch - ApiPlatform\Metadata\Delete serializer: - hydra_prefix: true + hydra_prefix: false What changed?

47. What changed? No more PUT operation by default Hydra prefix disabled ApiPlatform/{Api,Exception} moved to ApiPlatform/Metadata Listeners are no longer used* * only useful when using controllers on API Resources

48. Hydra prefix? GET /books Content-Type : application/ld+json { "@context" : "/contexts/Book" , "@id" : "/books" , "@type" : "Collection" , "totalItems" : 4 , "member" : [ "/books/73" , "/books/74" , "/books/75" , "/books/76" ] } GET /books Content-Type : application/ld+json { "@context" : "/contexts/Book" , "@id" : "/books" , "@type" : " hydra: Collection" , " hydra: totalItems" : 4 , " hydra: member" : [ "/books/73" , "/books/74" , "/books/75" , "/books/76" ] }

49. composer require api-platform/symfony:^4.0.0 Install API Platform 4 composer require api-platform/laravel

50. Thanks! SPONSOR ME! github.com/soyuka

51. Thanks! Sponsor Me! github.com/soyuka Buy or merch! | 10 000 € PHYSICAL COVERAGE

52. Dos / don’t Errors openapi + defaults ?

53. Error management Static HTTP Headers Denormalize type Query Parameter New in API Platform 3.4 / 4.0

54. Error management Static HTTP Headers Denormalize type Query Parameter New in API Platform 3.4 / 4.0

55. New in API Platform 3.4 / 4.0 POST /import HTTP/2 Content-Type : application/json [{ "name" : "Kévin" }, { "name" : "Antoine" }]

56. use ApiPlatform \ Metadata \ Post ; class ValueObject { public string $name ; } #[ Post ( uriTemplate : '/import' , denormalizationContext : [ 'deserializer_type' : 'ValueObject[]' ], validate : false , // we don't validate lists processor : [ self :: class , 'process' ] )] class Book { public static function process ( mixed $data ) { // Do something with the list of ValueObject } } New in API Platform 3.4 / 4.0 custom validation => processor

57. ESA (frontend tools + mercure powerful) Handle links Parameters Iri Converter Subtree split ? Allow create ? NoCode version xD Don’t fight, win. Parameter validation + security + docs + filter aliases News: doctrine enum filter, hydra prefix, event listeners Backed enum resources + doctrine filter Openapi_api_override_response Error custom feature