Docs for the Mercure support

core/mercure.md

@@ -0,0 +1,114 @@
+# Pushing Live Updates Using the Mercure Protocol
+
+API Platform can automatically send real time updates to the currently connected clients (webapps, mobile apps...) using [the Mercure protocol](https://mercure.rocks).
+
+> *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)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+
+![Mercure subscriptions](images/mercure-subscriptions.png)
+
+## Installing the Mercure Support
+
+The Mercure support is already installed, configured and enabled in [the official distribution](../distribution/index.md).
+If you use the distribution, you have nothing more to do, and you can jump 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](https://github.com/symfony/mercure-bundle):
+
+First, [download and run a Mercure hub](https://github.com/dunglas/mercure#hub-implementation).
+Then, install the Symfony bundle:
+
+     $ composer require mercure
+
+Finally, 3 environment variables [must be set](https://symfony.com/doc/current/configuration/external_parameters.html):
+
+* `MERCURE_PUBLISH_URL`: the URL that must be used by API Platform to publish updates to your Mercure hub (can be an internal or a public URL)
+* `MERCURE_SUBSCRIBE_URL`: the **public** URL of the Mercure hub that clients will use to subscribe to updates
+* `MERCURE_JWT`: a valid Mercure [JSON Web Token (JWT)](https://jwt.io/) allowing API Platform to publish updates to the hub
+
+The JWT **must** contain a `mercure.publish` property containing an array of targets.
+This array can be empty to allow publishing anonymous updates only.
+[Example publisher JWT](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InN1YnNjcmliZSI6WyJmb28iLCJiYXIiXSwicHVibGlzaCI6WyJmb28iXX19.LRLvirgONK13JgacQ_VbcjySbVhkSmHy3IznH3tA9PM) (demo key: `!UnsecureChangeMe!`).
+
+[Learn more about Mercure authorization.](https://github.com/dunglas/mercure/blob/master/spec/mercure.md#authorization)
+
+## 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
+<?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](images/mercure-discovery.png)
+
+Clients generated using [the API Platform Client Generator](../client-generator/index.md) will use this capability to automatically subscribe to Mercure updates when available:
+
+![Screencast](../client-generator/images/client-generator-demo.gif)
+
+[Learn how to use the discovery capabilities of Mercure in your own clients](https://github.com/dunglas/mercure#examples).
+
+## Dispatching Private Updates (Authorized Mode)
+
+Mercure allows to dispatch [private updates, that will be received only by authorized clients](https://github.com/dunglas/mercure/blob/master/spec/mercure.md#authorization).
+To receive this kind of updates, the client must hold a JWT containing at least one *target* marking the update.
+
+Then, hint API Platform to dispatch the updates only to the selected targets:
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(mercure={"a-group", "another-group"})
+ */
+class Book
+{
+    // ...
+}
+```
+
+It's also possible to execute an *expression* (using the [Symfony Expression Language component](https://symfony.com/doc/current/components/expression_language.html)), to generate a dynamic list of targets:
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(mercure="object.owners")
+ */
+class Book
+{
+    public $owners = [];
+   // ...
+}
+```