I’m glad to announce the immediate availability of API Platform 2.2 beta 1. This is a huge release that comes with a lot of exciting features including (but not limited too):
- GraphQL and JSON API support
- Symfony 4 / Flex integration
- API Platform Admin integration (built with ReactJS and Admin On Rest)
- ReactJS and Vue.js Progressive Web App generators integration (a React Native app generator is also available)
- Revamped Docker containers for both PHP and JavaScript components, including out of the box support for HTTP2, HTTPS and a built-in invalidation-based cache mechanism using Varnish
- The ability to deploy in seconds in any Kubernetes cluster
- A new, super-easy, way to register filters through annotations
- And literally dozens of developer experience, performance and quality improvements
V2.2 will definitely be the best version of API Platform, and is probably the most advanced “full-stack” solution to create API-driven projects. The paradigm shift introduced by this new version has been detailed in my talk during the SymfonyCon 2017.
It took 6 months and 483 commits from more than 60 contributors to craft this version. The documentation has also been dramatically improved, even if some work is still to do (upgrading the getting started guide and migrating all articles to the new Flex directory structure, finish to document some new features).
Thank you very much to all contributors of the project! You rock!
Let’s see more in depth all of these new features:
The New Distribution
The easiest way to get started with API Platform has always been to use the provided Docker setup. In version 2.2, the Docker configuration has been totally redesigned to fit with the new features provided by Symfony Flex and to integrate our JavaScript components.
To get started:
- Download the last release
- Decompress the archive and open a terminal in the resulting directory
- Run docker-compose up
You get:
– An API skeleton following the Flex directory structure. Just add classes representing your public data model (see the example below) to get a working hypermedia and/or GraphQL web API.
The API is available in HTTP/2 and HTTPS thanks to the provided development proxy. It also automatically benefits from the API Platform’s built-in cache mechanism (the Varnish container is also provided). CORS headers are automatically configured. As you can see, the nice documentation is – of course – still available if you open the entrypoint in a browser.
– A ReactJS Progressive Web App skeleton with a fancy welcome page designed by Laury Sorriaux:
Execute docker-compose exec client generate-api-platform-client to bootstrap a nice and fully-featured Progressive Web App (that can even work offline) using React, Redux and Bootstrap 4 and respecting accessibility recommendations.
To generate the PWA, the tool parses the API hypermedia description automatically generated in the Hydra format by the API component. This generator can work with any server exposing a Hydra documentation (done with API Platform or not).
The tool also has Vue.js, React Native and TypeScript skeletons thanks to the great contributions of Alain Hippolyte, Piotr Synowiec and Antoine Bluchet.
Read the full documentation of the API Platform Client Generator.
– Last but not least, a dynamically generated admin for the API is also automatically available:
Like the client generator, the API Platform Admin component also leverages the Hydra documentation to automatically guess the structure of the data exposed by the API.
Because it is built on top of React and Admin On Rest (aka React Admin), the UI is fully customizable.
Morgan Auchedé is the new maintainer of this component, and has greatly improved it since its initial release.
– In this version of API Platform, the MySQL container has been replaced by a Postgres one.
Instant Kubernetes Deployment
Kubernetes has become the most popular way to deploy, run and manage containers in production. Both Google Cloud Platform, Microsoft Azure and Amazon Web Services provide managed Kubernetes environment.
API Platform 2.2 contains a built-in Helm (the k8s package manager) chart to deploy with ease:
helm upgrade --install ./api/helm/api \
--set php.repository=gcr.io/test-api-platform/php \
--set nginx.repository=gcr.io/test-api-platform/nginx \
--set secret=MyAppSecretKey \
--set postgresql.postgresPassword=MyPgPassword \
--set postgresql.persistence.enabled=true \
--set corsAllowUrl='^https?://[a-z\]*\.mywebsite.com$'
Your app is now up and running in a managed cluster! Read the related documentation to learn more about the Kubernetes support.
GraphQL Support
GraphQL is a query language for APIs designed by Facebook that is becoming a very popular alternative to the REST pattern. GraphQL support has been the most wanted feature for a while, it is now fully implemented!
The new GraphQL subsystem of API Platform now supports:
- 100% of the main specification, including queries (read) and mutations (write)
- 100% of the GraphQL Relay Server Specification (= compatibility with both Relay and Apollo clients)
- Pagination
- Filters (built-in and custom ones, see below)
- Validation
- Access control rules
- Generation of optimized SQL queries (automatic joins depending of requested data)
- The GraphiQL UI
To enable the GraphQL support, you just have to install the GraphQL PHP library:
docker-compose exec php composer req webonyx/graphql-php
Then, create an API Platform entity, as usual:
<?php
namespace App\Entity;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;
/**
* An organization.
*
* @ApiResource
* @ORM\Entity
*/
class Organization
{
/**
* @ORM\Id
* @ORM\Column(type="guid")
* @Assert\NotBlank
*/
public $id;
/**
* @ORM\Column(type="text")
* @Assert\NotBlank
*/
public $name;
}
Yes, both GraphQL and REST formats can be used for the same entity! Thanks to API Platform’s hypermedia support, you can even run a GraphQL request, then apply REST operations to the retrieved resources using their IRIs! The best of both worlds.
Your GraphQL API is ready! Browse https://localhost:8443/graphql :
There is a lot to say about the GraphQL support, how to use it in collaboration with REST and how to apply fine-grained configurations. I’ll write a follow-up post dedicated to it, stay tuned!
The GraphQL support is an important team work of Raoul Clais, Alan Poulain, Baptiste Meyer and myself.
JSON API Support
JSON API is a rising, well designed, hypermedia format. Unlike JSON-LD (the default format exposed by API Platform), it’s not a web standard; and it has less features but it is also simpler to learn and understand.
With API Platform 2.2, you don’t have to choose, you can have both! And even more because API Platform supports out of the box JSON-LD/Hydra, HAL, JSON API, YAML, XML, raw JSON and as we’ve seen just before, GraphQL.
To enable JSON API, add the following config:
# config/packages/api_platform.yaml
api_platform:
# ...
formats:
# ...
jsonapi: ['application/vnd.api+json']
error_formats:
# ...
jsonapi: ['application/vnd.api+json']
Easy enough?
The JSON API support has been contributed by Hamza Amrouche, Hector Hurtarte and Baptiste Meyer.
Declaring API Filters Using Annotations
The API Platform filtering system is very powerful. It contains a lot of built-in filters and can easily be extended. However, until now, it wasn’t really easy to configure: it was requiring to declare services manually.
Because Symfony Flex is all about service autowiring and autoconfiguration, simplifying the filters configuration was a top priority task.
Hopefully, Antoine Bluchet created a nice way to do it using annotations:
<?php
// api/src/Entity/Organization.php
namespace App\Entity;
use ApiPlatform\Core\Annotation\ApiFilter;
use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter;
/**
* ...
*/
class Organization
{
// ...
/**
* @ApiFilter(SearchFilter::class)
* ...
*/
public $name;
}
Nothing more! You can now filter the collection of organizations by the name property, both with REST and GraphQL!
In addition to these main features, a lot of other configuration options and various improvements have been introduced. Read the full changelogs for more information:
Help Us: Test, Star, Spread the Word!
If you have some existing API Platform projects, or if you want to give a try to the framework, please test this new version and report any problem on our GitHub issue tracker!
If you like API Platform, please tell the world and give us a star on GitHub.
Since API Platform 2.2, the Symfony Thanks command is also shipped with API Platform. Thanks to this tool, you can send a star to all the PHP libraries you use in your project (including API Platform) by simply running: docker-compose exec php composer thanks
If you want to learn API Platform, come to one of the workshops organized during these upcoming tech conferences:
Don’t miss the next opportunities to learn @ApiPlatform during a 1 day workshop:
– « Creating and deploying API Platform apps on @platformsh » / @APIdaysGlobal
– « Mastering the API Platform’s server component » / @symfony_live Paris (2 sessions) then Phantasialand— Kévin Dunglas (@dunglas) January 23, 2018
2 thoughts on “API Platform 2.2: GraphQL, JSON API, React admin and PWA, Kubernetes instant deployment and many more new features”