Abstract:
API Platform is a popular framework to build API-driven projects. The server component is built on top of Symfony. It enables to create modern, extensible and secure web APIs very easily: design the public data model, and that's all, you get a fully-featured API!
But API Platform also provides awesome client-side components (written in JS) working with the server component, and with any other modern REST API! These components include a smart admin builder and client generators supporting React, Vue, React Native, Next, Quasar and Vuetify! Last but not least, API Platform comes with the Docker images and the Kubernetes chart you'll need to deploy in production, in seconds.
Since its introduction during SymfonyLive Paris 2015, API Platform evolved a lot! It is now recognized as the easiest and most powerful set of tools to build and use new web APIs, even outside of the PHP world. During this talk, will discover the new best practices and the unknown gems provided by the framework.
Transcript:
Hi, everybody, let's talk about the new features of API platform. API Platform is a full stack framework for API driven Web projects. Some key points: API Platform lets you building projects very easily, even if you're not an API specialist.
Even if it is very easy to use, it supports by default and without efforts the most modern API technologies.
By default, it will expose an hypermedia API, Mercure to push data from the server to the clients, it supports Vulcain to preload relations of your resources.
It supports the GraphQL format from Facebook. API Platform is a full stack framework. It contains a library to create your API servers, but it also contains libraries written in JavaScript to consume the API, to build Web applications, to build native mobile applications, to build Internet of Things (IoT) devices.
Finally, API platform contains the recipes to deploy this project, both the server side and the frontend parts in production, in your own servers or in the cloud. Even if it is focused on being very easy to use, API Platform is customizable, extensible, modular, you can tweak, replace, change everything and you can very easily plug your own custom business logic.
So the main components of API Platform are the API component, so it's the most popular one, it’s a PHP library and some integrations with popular other PHP libraries allowing to build APIs with ease. There is also the Schema Generator component. So this one is probably the less popular component in the API platform ecosystem. But it's my favorite and actually it deserves a whole talk. Basically, it allows to use definitions of public vocabularies and public schemas for instance Schema.org or, I don't know, the the public data model of the European Union and to generate code and PHP classes and an API Platform API, from these public RDF descriptions.
There is also JavaScript components allowing to create frontend applications, consuming and creating APIs. There is an admin component that is similar to Sonata or EasyAdmin, but this component is written entirely in JavaScript with the React Library. So it has a very nice user experience and it is totally dynamic. You just load a single React component and this component will find the description of your API. It can be an Hydra or an OpenAPI description. It works with any API, with a proper machine-readable documentation and dynamically it will be the screens of the administration and it is fully customizable, it’s a very nice tool. And finally, we have a code generator called the Client Generator component, and it works a bit like the admin component. It will find the description of the API and it will allow us to generate code from this description.
So how to build an API Platform project? First, you will design the public shape of your API, the resources how they are organized, the types, their properties, their relations. So basically you will think about how the clients developers will use your public API, then API platform will give you all the infrastructure to create an API implementing this public data model. It will also generate automatically the documentation, the API documentation and it will provide you a lot of features like the ability to add security rules, access control rules, the user system and things like that.
At this point, you have your server-side API ready. So you can consume this Web API using the client site tools provided by API Platform, the client generator. This tool can generate native mobile apps, Progressive Web Apps, a lot of things like that, and the admin generator. We also provide tools to write automated tests, both server-side and client-side. And finally, we provide a Kubernetes chart and a Docker Compose set up to deploy your application in production. So I think that most of you already used or at least tried API Platform, but let's remember the basics of how it works and the design of the tool.
So first, you need to install the project. So there are several ways to do it, but the easiest way is to go on the API platform website, download the archive, type docker-compose up and everything configured for you, you don't even need to have PHP or a database installed locally, you have a working project. All the configuration required is directly in this template directory that you have download from the API Platform website. And so you must design your public data model. API Platform is both a design-first and a code-first framework. So the mental process of building an API with API Platform will start with a design first approach. So you will describe the shape, the structure, the shape of the resources that you will expose through your API as a set of plain old PHP classes. But these classes are mostly structured and it could be YAML files like with OpenAPI. It could be just a documentation explaining how it should look. It's just a way to encode the public data structure of the API using the PHP language.
So these classes representing the public shape of your API will act as Data Transfer Objects. So API Platform will use these objects to store the data that will be sent to the clients and encode these objects as JSON and bring back the data put by the clients to the server, and extract the content from the JSON documents, hydrate the Data Transfer Objects and give them to you to use them in your business logic. So as we use PHP classes to design the API, we of course can use the full expressivity of the PHP language and use types and also use the PHP documentation to add human readable documentation. So here is a basic example of how to use API Platform, so in this example, we describe a book class. So it will be basically a Book document encoded in JSON in our API. We use the types to describe the types of the properties. We set the constructor to tell that the object must have an ID and a title to be constructed.
We had some PHPDoc and to hint API platform that this class is a special one that describes a public data model. we mark it with the @ApiResource annotation. And that's all. Just with that we get a fully, almost fully working API. The standard REST routes are automatically registered just by using the metadata, provided in the PHP class.
A machine-readable API documentation is generated, actually several formats are supported. By default the OpenAPI format will be used as well as the Hydra documentation format. And you can also enable the GraphQL support if you want to generate a GraphQL Schema. API Platform is also able to generate JSON Schemas.
And in addition to this machine readable documentation, we provide some tools, for instance Swagger UI to display them, to display these documentations for humans. There is only two things that you need to do, API Platform provides all the infrastructure to build modern APIs, but the domain, the business logic, is your own and you have to write it. So API Platform provides extension points you have to use to plug in your domain, your own business logic. There are several interfaces to implement and then everything is wired automatically thanks to the autowiring feature of Symfony.
First, you need to write a Data Provider, the data provider will have to fetch the data from your persistence system, from your database.
You can use, for instance, the Doctrine ORM, or MongoDB, or Google Firebase, everything will n OK, and you fetch the data, you hydrate our DTOs and you return our DTOs. A collection for the lists, an item for the single endpoints. The supports methods allows to check which classes are supported by this data provider, because you can have as many data providers as you need. For write requests, it's almost the same thing, you have another interface to implement, the Data Persister interface and the data you sent to the API will be passed as an argument of these methods so for POST, PATCH, PUT methods, you will have to implement the persist method to fetch the data from the DTO and save it in your database or something like that. And for a delete request, then you will have to remove this, the passed object. The supports method is the same as for the data providers. Data providers and data persisters work both for REST formats and for GraphQL. So with these two classes you have support for REST and GraphQL with the same code.
And just with that, you can use all the features of API Platform, including authorization and authentication data validation, pagination, filtering, sorting realtime push using the Mercure protocol, Vulcain, you get native support for a lot of documentation UIs, including including Swagger UI, Redoc, Graphiql. You have all the tools you need to write your automated tests. You have natively an hypermedia API. You have native support for HTTP/3, for the RDF standards, for GraphQL, for other community formats such as JSON:API, HAL, JSON Schema, just because API Platform provides you all the needed infrastructure. API platform also comes with a Symfony Integration's because, after all, it's SymfonyCon and both projects are very close and related and both core teams are working a lot together. So the core library is the main PHP library of API Platform, and it's a standalone PHP library built on top of Symfony components. Then you have the Symfony Bundle called ApiPlatformBundle, which is shipped with Symfony when you install API Platform by default and it contains all the integrations with Symfony, for instance Routing, the Serializer and things like that.
There are also optional bridges, one for Doctrine, one for MongoDB and one for Elasticsearch. If you use these bridges, then the persistance will be handled automatically for you by API Platform. It's totally optional. It's maybe not what you need, but it's very practical for small APIs, for prototyping and for Rapid ApplicationDevelopment. For instance, if you want to share the public data model of the API with your internal database data model, then you can map the same class with @ApiResource and as a Doctrine entity with the Doctrine annotation and then, automatically, the persistence and the querying is handled for you. And you get a lot of features, including native filters, something automatic pagination and a lot of things. But keep in mind that it's totally optional. Another very interesting feature provided by API Platform, the integration with MakerBundle. So with this tool, you can write your fully working Web APIs, supporting most modern formats without coding at all. So you run the make:entity command and you get an interactive form where you can describe the public data model of your API, the name of the resources, the name of the properties, their types, the relations between the resources and the all the PHP is generated for you with both the API Platform and the Doctrine mapping. So when the command ends, you have a working API. And it is very practical for prototyping.
So let's speak about the very new features of API Platform. I use a very specific methodology for the open source projects I work on. I called that Conference Driven Development. Basically, it means that I submit abstracts to some conferences and sometimes one of these abstracts is selected. And then what is described in this abstract must be implemented. So I have some weeks to implement it. And of course, it's what I've done today for this talk.
The last stable version of API Platform, the last minor version is one year old. It was API Platform 2.5. And as you can see in the screenshot, in one year, a lot of work has been done by the community working on API Platform and especially the core repository.
So for SymfonyWorld, I'm very happy to announce the immediate availability of API platform 2 6 alpha version. It is out. It has been released a few hours before the conference. So you can try everything that I will show right now, just now. So let's start with the new features introduced in the core library. First, we have support for PHP 8, and especially for PHP 8 attributes. So it has been released the past week. And instead of the ugly annotations that we were using, now, with API Platform 2.6, you can use the #ApiResource attribute, for instance, and add native support. for this brand new feature. The constructor is using another new feature of PHP 8 called constructor promotion, basically with the syntax, the arguments of the construct method are also public properties for this class. So it has been a tedious work and there are still some some specific annotations to convert in PHP 8 attributes, but the most common annotations in API Platform can now be used with PHP 8 attributes.
Another very interesting feature in API Platform 2.6 is the ability to define a default configuration that will be applied to all operations and all resources, for instance, in this example, I said that I want to enable only to GET operation for all resources. So with this setting, you don't have to set that you only want to enable to get some every classes as before. It will be the default, and it will be enabled automatically. So this setting this API is read-only. Of course, if you you can override the configuration by putting the specific attribute in the #ApiResource attribute or annotation on a specific resource. So this future is a very good improvement in terms of usability.
Another very nice feature is the ability to add access controls to properties. Access controls for resources were supported from a long time, but it wasn't possible to say, OK, I want to serialize some properties only for the admins, for instance. Now it's supported. So you can use the expression language component of Symfony to tell that, for instance, this property must be serialized only for admins, and other people will not see it.
A lot of work have been done in this Core PHP library. So, for instance, we fixed all depreciations regarding PHP 8. So the library is now fully compatible with PHP 8.
Support for GraphQL subscription: the ability to send updates to clients when something changes to the site has been added and it's using Mercure.
Mercure support for MongoDB has been added.
Support for the new Symfony Serializer annotations @Ignore and @SerializedName has been done. A new builder has been created for the OpenAPI documentation, allowing to customize the output of the OpenAPI documentation very easily. Better support for composed identifiers has been merged to, and we have now an improved support for the Vulcain protocol.
Now let's talk about the other tools in API Platfotm. So the client generator is a JavaScript application allowing to scaffold applications, by parsing an API documentation. It can work with any API even if it's not an API using API platform. If this API as an Hydra documentation or an OpenAPI documentation, you can use this tool.
This tool has a system of skeletons so it's very easy to add support for a new JavaScript framework, so actually you can generate any code in any language. Basically, these generators will have the representation of the structure of the API passed, and then it will be able to generate code by using that.
In 2.5, we had support for generating TypeScript model definitions from the API documentation. For generating Progressive Web Apps using React and Redux, but without Server-Side Rendering. Support for Vue.js. For React Native to build native mobile apps and for the Quasar and Vuetify frameworks that are JavaScript frameworks built on top of Vue.js.
In API Platform 2.6, I am very proud to announce the immediate availability of a new generator for the very popular Next.js framework. Next.js is a very easy to use framework for React. And this framework has support for Server-Side rendering. It means that when using Next.js the same JavaScript code will be executed / can be executed / in the browser and server side with Node. So there is no search engine optimization problems anymore by using this technology.
So Next.js is a very nice tool and we have a generator allowing to generate a fully working Next.js app just from your API documentation now in API Platform. And the generator is now the default one, when you install API Platform by downloading it from the official website, you get a container with a proper Next.js installation and the generator to scaffold your Next application. How does it works? You just run the generate-api-platform-client command. You can pass the URL of the API if it's not the default one if you want and you get all the JavaScript code generated for CRUD applications using the API and Next.js. We also added support for the Nuxt.js framework. It's more or less the same kind of tools as Next.js, but using Vue.js so you can choose your preferred JavaScript too.
We also improved a lot the API Platform developer experience. In 2.5, when you run docker-compose up you get all these services: a service specific for TLS support and HTTPS / HTTP/2. Mercure, Vulcain, and NGINX server, one server for the client, one server for the admin, the database and PHP.
So it's a lot, it works, but it's a lot to learn. It can be hard to deploy if you have some specific setups, when something goes wrong, when you want to fix something. There are a lot of moving parts.
So in API Platform 2.6, we change that to use the Caddy Server. Cady is a very popular Web server, allowing to use modules to do everything that is needed in a modern Web application. So Caddy is a very fast web server written in Go, it’s fully open source, it is built from the ground up to be extensible. It have native support for PHP, it’s just one line of command, it has native support HTTPS and it will use Let’s Encrypt to generate the certificate automatically and it can even generate the certificate on localhost. It has support for HTTP/3, it is cloud native and there's a lot of cloud related features.
Caddy has almost everything needed by API Platform, except a Mercure module, a Vulcain module, and a good Varnish-like HTTP cache module. So I created the Mercure module. And the Vulcain module. And I'm working on a brand new HTTP cache module for Caddy. It's working, but it's still early in the early stages. So now in API Platform, you just have to mandatory services: PHP and Caddy server, with all the modules. There is still Postgres - it’s optional - and there is only one JavaScript container containing Next.js and the admin interface. They are in the same image.
If you don't want to use JavaScript, then you just need the PHP library. There is also Symfony Dockr. It is the same thing. It's also based on Caddy; but it provides only PHP and Symfony. No Postgres, no API Platform, no code.
If you want to add support for Postgres and the ORM, you can use the new Flex support for Docker and you type « docker-compose exec php composer req orm » and Flex will automatically add a Postgres service to your docker-compose.yaml file and install the Postgres driver. Then you can install API Platform like on any Symfony project using composer.
And if you don't want to use Docker at all, you can just download the proper Caddy binary and you can even build your own and cherry pick the modules you want.
I also published a new component called ActivityPub Component. So if you are interested in the Web decentralization and the ability to fight against the censorship promoted by Facebook, Twitter and most major tech platforms, you can take a look at my talk « save the web, decentralize » and you will learn that the W3C is promoting a new protocol allowing to build decentralized social networking applications. It’s called « ActivityPub » and a lot of software already implement it, including Mastodon, PeerTube, PixelFed, Mobilizon and a lot of other tools that can work together using this protocol.
If you want to build such applications, now you can use the API Platform ActivityPub Component. You can install it on any Symfony or API Platform project and it adds support for this protocol for your own social network application built in PHP and with Symfony.
Finally, everything in API Platform is only possible because of the community. We have a lot of contributors working on the code but also on the documentation and support and making talks and YouTube videos… We have a very nice sponsor paying for a large part of the development, which is Les-Tilleuls.coop.
So to thank the community, we added new pages on the website showcasing the work of the contributors. So now everybody, each API Platform contributor has a dedicated page with the list of his/her contributions and a link to his/her GitHub profile, and to his/her personal website. Also for people having contributing during Hacktoberfest, drop us a mail, because we will send you a T-shirt.
Just one more thing, the next release of API Platform after 2.5 will be API Platform 3. API Platform 3 will support only PHP 8. It will have better support for subresources. There is an ongoing refactoring, subresources first class citizen in API Platform 3 and you will be able to have write support for subresources.
API platform 3 will be the same code that API Platform 2.7 but without the backward compatibility layer. So both API Platform 3 and 2.7 will be released at the same time, like Symfony 4.4 and 5.0.
If you like my work if you like this talk, if you like API Platform, don't hesitate to sponsor me on GitHub it helps me working more on this kind of talks but also on the maintenance and on the new feature of the framework.
Thank you very much. And if you have some time, please download and test API Platform 2.6 alpha on your own projects so we can find and squash bugs. Thank you very much.
dunglas
sr2mg4
tomokusaba
taowata
tonkotsuboy_com
ogiwarat
jpt_corp_official
kazuhitoyokoi
antonicg
uhooi
philipschwarz
stewemetal
kizuku_miyagi
marktimemedia
akmur
pauljervisheath
garrettdimon
sachag
samlambert
schacon
addyosmani
hannesfritz
tammielis
mza
deanohume