Skip to content

Kévin Dunglas

Founder of Les-Tilleuls.coop (worker-owned cooperative). Creator of API Platform, FrankenPHP, Mercure.rocks, Vulcain.rocks and of some Symfony components.

Menu
  • Talks
  • Resume
  • Sponsor me
  • Contact
Menu

API Platform 2.1 Feature Walkthrough: Create Blazing Fast Hypermedia APIs, Generate JS Apps

Posted on June 8, 2017September 18, 2017 by Kévin Dunglas

Update September 18: API Platform 2.1 has now been released. This blog post has been updated according to the syntax used in the stable version.

Finally, after more than 1 year of dev and 3 months of beta, @ApiPlatform 2.1 is out 🍾🎆🙌. A big THANKS to all contributors! #API #PHP #React

— Kévin Dunglas (@dunglas) September 8, 2017

 

The new UI of API Platform 2.1

API Platform is a framework designed to make the creation of API-based information systems easier. It provides server-side tooling to create modern hypermedia and Linked Data APIs in just a few minutes. This new version introduces client-side tools to bootstrap Single-Page Applications using ReactJS by consuming the autogenerated documentation of the API.

Six months after the release of API Platform 2, I’m very excited to announce the immediate availability of the first beta of API Platform 2.1!

The changelog is huge, more than 200 commits by dozens of developers have been merged. I think we can say that this release will be great!

Let’s review the most interesting new features. If you just want to try it, the demo has been upgraded to use this new version and you can download it on GitHub.

A ReactJS-based Admin System

API Platform automatically exposes API documentations respecting the Hydra (W3C) and Swagger/Open API open standards. We created a dynamic administration system built on top of the awesome Admin On Rest library that takes advantage of the Hydra format.

Just with this line of code <HydraAdmin entrypoint=”https://demo.api-platform.com”/>, you will get the following result:

Replace https://demo.api-platform.com by the URL of any API documented with Hydra and you will get a beautiful material design admin for it with:

  • list, create, show, edit screens as well as a delete button
  • suitable inputs and fields according to the API doc (e.g. number HTML input for numbers, checkbox for booleans, selectbox for relationships…)
  • suitable inputs and fields according to Schema.org types if available (e.g. email field for http://schema.org/email)
  • relationships
  • pagination
  • client-side validation for mandatory fields
  • server-side errors displaying (e.g. advanced validation)

It means that any API Platform API can now have an admin for free! The admin is fully customizable, a follow up post will come.

A React/Redux Webapp Generator

The admin is dynamic, no code generation happens. But sometimes it’s interesting to be able to generate some code to bootstrap a project. It’s exactly what the new api-platform-generate-crud tool does. It parses the Hydra documentation and generates a basic ReactJS webapp with the following features:

  • generation of high-quality ES6 components and files built with React, Redux, React Router and Redux Form including:
    • a list view
    • a show view
    • a creation form
    • an edition form
    • a deletion button
  • generation of the suitable HTML5 input type (number, date…) according to the type of the API property
  • display of the server-side validation errors under the related input (if using API Platform Core)
  • client-side validation (required attributes)
  • the generated HTML is compatible with Bootstrap and includes mandatory classes
  • the generated HTML code is accessible to people with disabilities (ARIA support)
  • the Redux and the React Router configuration is also generated

Thanks to Piotr Synowiec for his contributions and fixes to those frontend tools!

Builtin HTTP Cache Invalidation System

Exposing a hypermedia API has many advantages. One of them is the ability to know exactly which resources are included in HTTP responses created by the API. We used this specificity to make API Platform apps blazing fast.

When the new cache mechanism is enabled, API Platform collects identifiers of every resources included in a given HTTP response (including lists, embedded documents and subresources) and returns them in a special HTTP header called Cache-Tags.

A cache reverse proxy supporting cache tags (Varnish, CloudFlare, Fastly…) must be put in front of the web server and store all responses returned by the API with a high TTL. When a resource is modified, API Platform takes care of purging all responses containing it in the proxy’s cache. It means that after the first request, all subsequent requests will not touch the web server, and will be served instantly from the cache. It also means that the content served will always be fresh, because the cache is purged in real time.

The support for most specific cases such as the invalidation of collections when a document is added or removed or for relationships and inverse relations is built-in.

We also included Varnish in the Docker setup provided with the distribution of API Platform, so this new feature works out of the box.

Integration with Varnish and the Doctrine ORM is shipped with the core library. You can easily implement the support for any other proxy or persistence system.

A big thanks to Jérémy Derussé, Teoh Han Hui, Fabien Bourigault, Antoine Bluchet and all other involved contributors for their in-depth reviews and good advices.

A detailed blogpost about this feature will follow.

Per Resource Authorization Mechanism

Thanks to the API Platform’s events and the extension system, it was already easy to configure basic authorization rules. In the version 2.1, we introduced an easy way to configure fine grained authorization rules directly from resource classes.

In the following example, only the logged in admins can access all operations related to the SecuredResource. However, regular users owning a specific resource can also access it:

<?php

namespace AppBundle\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ApiResource(
 *     attributes={"access_control"="has_role('ROLE_ADMIN')"},
 *     itemOperations={
 *         "get"={"method"="GET", "access_control"="object.getOwner() == user"}
 *     }
 * )
 * @ORM\Entity
 */
class Secured
{
    /**
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    public $id;

    /**
     * @ORM\Column(type="text")
     */
    public $owner;
}

Under the hood, this new feature uses Symfony’s access control expressions. The object variable value is the current resource (or collection of resources) while the user variable contains an instance of the Symfony’s user currently logged in.

Subresources Support

Having the ability to expose subresources was one of the most requested features. It was already possible to use such URL patterns thanks to custom operations, but it was a bit complicated to do.

Fortunately Antoine Bluchet rolled up this sleeves and did an excellent job! As of API Platform 2.1, subresources are a first class citizen:

/**
 * @ApiResource
 */
class Product {
    /**
     * @ApiSubresource 
    */
    public $reviews; 
}

The previous snippet is enough to expose through http://example.com/products/1/reviews  the list of RelatedDummies resources related to the Dummy #1.

The documentations will also reflect the availability of this new URL.

New Filters

API Platform comes with 3 new useful filters that you will love.

property_filter

Baptiste Meyer contributed 2 of them. The first one, api_platform.serializer.property_filter, lets the client specify which properties the API must return.

When a resource is configured to use it, you can use the URL /products/1?properties[]=price&properties[]=currency to only serialize the properties “foo” and “bar” of this entity (all other properties will be ignored).

It’s also possible to list the properties of embedded resources with the following format: /products/1?properties[]=price&properties[brand][]=name.

group_filter

The second one, api_platform.serializer.group_filter is similar, but instead of choosing properties one by one, you can pass a list of serialization groups to apply using a URL like: /products/1?groups[]=detailed.

Those two filters allow to easily reduce the size of the returned resources to only include relevant data.

exists_filter

The last new filter, api_platform.doctrine.orm.exists_filter, was contributed by Teoh Han Hui. It allows to filter a collection on the existence of a specified value: /products?brand[exists]=0.

A Revamped API Doc UI

API Platform has a nice UI built with Swagger UI that is available for every URL of the API when requesting it from a browser (or any client sending a Accept: text/html HTTP header). In API Platform 2.1, we upgraded Swagger UI to its new major version (3.0), a full rewrite in ReactJS (API Platform + React = ❤️) including a bunch of UX improvements.

Laury Sorriaux took this opportunity to propose a great custom stylesheet improving the overall user experience and respecting our color scheme. It also contains an animation featuring our cute spider (he will get a name soon, stay tuned)!

Last but not least, Daniel Kiesel contributed to improve the integration with OAuth (and FOSOAuthBundle): it’s now possible to login with OAuth from the UI by just adding a few lines of config.

Brand New Docker Setup

One of the coolest features of API Platform 2 was the ability to run the app locally by just typing docker-compose up  and to deploy apps in a breath with Kubernetes or Docker Swarm.

In API Platform 2.1, we dramatically improved the Docker support:

  • All images are now using Alpine Linux (reduce the size, improve the security)
  • Nginx and PHP-FPM are now used instead of Apache and mod_php
  • Varnish has been added (see the section about the cache invalidation mechanism)
  • The Docker Compose file has been upgraded to the format v3
  • Many compatibility problems with Windows have been fixed
  • The performance when using Docker for Mac or Docker for Windows has been dramatically improved

This Docker setup supports any Symfony-based application. Just copy/paste it in your Symfony project.

Improving the Docker configuration was a hard and collaborative work. I want to especially thanks Jacques Lefebvre, Teoh Han Hui and Antoine Bluchet for the large numbers of hours they spent to make this possible.

Integration in Symfony Flex

You can’t have missed it, Symfony 4 will come with an exciting tool to install and manage your projects: Symfony Flex. API Platform is already officially supported by Flex and can’t be easier to install: just type composer req api

Fabien Potencier (the creator of Symfony) recorded a screencast showing how API Platform and Flex fit well together:

Impressive isn’t it? Flex only works with API Platform 2.1+. Older versions aren’t supported.

Of course, many other new features, fixes and improvements (especially regarding performance) have been merged, you can read the full changelog to learn more.

Next steps before the stable release:

  • Testing, testing and testing again. Please try the new features, upgrade your existing projects and run your tests suites against this new version! Report any problem on GitHub. It’s very very helpful to us!
  • Update the documentation and write new articles for the new features. They are already many pull requests opened, reviewing and improving them is much appreciated.

A last and big thanks to all the API Platform Core Team and especially to Teoh Han Hui, Antoine Bluchet, Baptiste Meyer and Hamza Amrouche for their detailed work reviewing all contributions and getting this beta out!

P.S.: Spread the word, please give us a star on GitHub or tweet about the release of this new version!

Related posts:

  1. Creating hypermedia APIs in a few minutes using the API Platform framework (APIDays)
  2. API Platform 2.0 released: creating powerful web APIs has never been so easy
  3. Creating a hypermedia API in 5 minutes with API Platform (Take Off Conf)
  4. API Platform 2.1: when Symfony meets ReactJS (Symfony Live)

7 thoughts on “API Platform 2.1 Feature Walkthrough: Create Blazing Fast Hypermedia APIs, Generate JS Apps”

  1. Pingback: API Platform 2.1 Feature Walkthrough: Create Blazing Fast APIs, Generate JavaScript Apps – Full-Stack Feed
  2. tseho says:
    June 10, 2017 at 3:08 pm

    Hello,

    The given example for subresource has a typo in it.

    It should be:
    @ApiProperty(subresource=true)
    instead of:
    @ApiProperty(subcollection=true)

    Reply
  3. Pingback: #API #Platform 2.1 #Feature #Walkthrough: Create #Blazing Fast #Hypermedia APIs, Generate #JS #Apps – Barki Mustapha IP Dev 💐🌹🌴🇲🇦
  4. Kegan VanSickle says:
    August 13, 2017 at 6:23 pm

    I have followed the instructions, and my screen for the API Admin just says “loading…”. I am wondering what I am missing.

    Reply
  5. Pingback: API Platform 2.2: GraphQL, JSON API, React admin and PWA, Kubernetes instant deployment and many more new features - software architect and Symfony expert
  6. Pingback: API Platform 2.3: Major Perf Improvement, API evolution/deprecation, Better Dev Tools and Much More! - software architect and Symfony expert
  7. Pingback: API Platform 2.3: performance boost, optimization of development tools | FreeCodeTutorial

Leave a ReplyCancel reply

Social

  • Bluesky
  • GitHub
  • LinkedIn
  • Mastodon
  • X
  • YouTube

Links

  • API Platform
  • FrankenPHP
  • Les-Tilleuls.coop
  • Mercure.rocks
  • Vulcain.rocks

Subscribe to this blog

Top Posts & Pages

  • Symfony's New Native Docker Support (Symfony World)
  • JSON Columns and Doctrine DBAL 3 Upgrade
  • Securely Access Private Git Repositories and Composer Packages in Docker Builds
  • Develop Faster With FrankenPHP
  • Preventing CORS Preflight Requests Using Content Negotiation
  • FrankenPHP: The Modern Php App Server, written in Go
  • Running Laravel Apps With FrankenPHP (Laracon EU)
  • Generate a Symfony password hash from the command line
  • How to debug Xdebug... or any other weird bug in PHP
  • 6x faster Docker builds for Symfony and API Platform projects

Tags

Apache API API Platform Buzz Caddy Docker Doctrine FrankenPHP Go Google GraphQL HTTP/2 Hydra hypermedia Hébergement Javascript JSON-LD Kubernetes La Coopérative des Tilleuls Les-Tilleuls.coop Lille Linux Mac Mercure Mercure.rocks Messagerie Instantanée MySQL performance PHP Punk Rock Python React REST Rock'n'Roll Schema.org Security SEO SEO Symfony Symfony Live Sécurité Ubuntu Web 2.0 webperf XML

Archives

Categories

  • DevOps (84)
    • Ubuntu (68)
  • Go (17)
  • JavaScript (46)
  • Mercure (7)
  • Opinions (91)
  • PHP (170)
    • API Platform (77)
    • FrankenPHP (9)
    • Laravel (1)
    • Symfony (97)
    • Wordpress (6)
  • Python (14)
  • Security (15)
  • SEO (25)
  • Talks (46)
© 2025 Kévin Dunglas | Powered by Minimalist Blog WordPress Theme