Api Platform Conference

The conference dedicated to API Platform and its ecosystem

Sep 15, 16 2022 | Lille & online

Creating Async APIs using the Mercure Protocol

API Platform can automatically push the modified version of the resources exposed by the API to the currently connected clients (webapps, mobile apps...) using the Mercure protocol.

Mercure is a protocol allowing to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way. It is especially useful to publish real-time updates of resources served through web APIs, to reactive web and mobile apps.

https://mercure.rocks

API Platform detects changes made to your Doctrine entities, and sends the updated resources to the Mercure hub. Then, the Mercure hub dispatches the updates to all connected clients using Server-sent Events (SSE).

Mercure subscriptions

Installing Mercure Support

Mercure support is already installed, configured and enabled in the API Platform distribution. If you use the distribution, you have nothing more to do, and you can skip to the next section.

If you have installed API Platform using another method (such as composer require api), you need to install a Mercure hub and the Symfony MercureBundle.

Learn how to install and configure MercureBundle manually on the Symfony website

Pushing the API Updates

Use the mercure attribute to hint API Platform that it must dispatch the updates regarding the given resources to the Mercure hub:

<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

#[ApiResource(mercure: true)]
class Book
{
    // ...
}

Then, every time an object of this type is created, updated or deleted, the new version is sent to all connected clients through the Mercure hub. If the resource has been deleted, only the (now deleted) IRI of the resource is sent to the clients.

In addition, API Platform automatically adds a Link HTTP header to all responses related to this resource class. This header allows smart clients to automatically discover the Mercure hub.

Mercure subscriptions

Clients generated using the API Platform Client Generator will use this capability to automatically subscribe to Mercure updates when available:

Screencast

Learn how to use the discovery capabilities of Mercure in your own clients.

Dispatching Private Updates (Authorized Mode)

Mercure allows dispatching private updates, that will be received only by authorized clients. To receive this kind of updates, the client must hold a JWT containing at least one target selector matched by the update.

Then, use options to mark the published updates as privates:

<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

#[ApiResource(mercure: ["private" => true])]
class Book
{
    // ...
}

It's also possible to execute an expression (using the Symfony Expression Language component), to generate the options dynamically:

<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

#[ApiResource(mercure: "object.mercureOptions")]
class Book
{
    public $mercureOptions = ['private' => true];

   // ...
}

Available Options

In addition to private, the following options are available:

  • topics: the list of topics of this update, if not the resource IRI is used
  • data: the content of this update, if not set the content will be the serialization of the resource using the default format
  • id: the SSE id of this event, if not set the ID will be generated by the Mercure Hub
  • type: the SSE type of this event, if not set this field is omitted
  • retry: the retry field of the SSE, if not set this field is omitted
  • normalization_context: the specific normalization context to use for the update.

What' new?

API platform conference 2022

Sep 15,16 2022: new edition of our conference dedicated to API Platform and its ecosystem!