Add docs for HTTP/2 Server Push (#714)

* Add docs for HTTP/2 Server Push

* Minor tweak

* Update push-relations.md

* @bendavies's review

Author: dunglas

core/performance.md

@@ -20,11 +20,36 @@ 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](https://varnish-cache.org/) in the [Docker setup](../distribution/index.md#using-the-official-distribution-recommended) provided with the
-distribution of API Platform, so this feature works out of the box.
+Integration with Varnish and Doctrine ORM is shipped with the core library, and [Varnish](https://varnish-cache.org/) is included in the [Docker setup](../distribution/index.md#using-the-official-distribution-recommended) provided with the
+distribution of API Platform.
+If you use the distribution, this 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.
+If you don't, add the following configuration to enable the cache invalidation system:
+
+```yaml
+parameters:
+    # Adds a fallback VARNISH_URL if the env var is not set.
+    # This allows you to run cache:warmup even if your
+    # environment variables are not available yet.
+    # You should not need to change this value.
+    env(VARNISH_URL): ''
+
+api_platform:
+    # ...
+    http_cache:
+        invalidation:
+            enabled: true
+            varnish_urls: ['%env(VARNISH_URL)%']
+        # Adds sensitive default cache headers
+        max_age: 0
+        shared_max_age: 3600
+        vary: ['Content-Type', 'Authorization']
+        public: true
+```
+
+Support for reverse proxies other than Varnish can easily be added by implementing the `ApiPlatform\Core\HttpCache\PurgerInterface`.
+
+In addition to the cache invalidation mechanism, you may want to [use HTTP/2 Server Push to pre-emptively send relations to the client](push-relations.md).
 
 ### Extending Cache-Tags for invalidation
 

core/push-relations.md

@@ -0,0 +1,39 @@
+# Pushing Related Resources Using HTTP/2
+
+>    HTTP/2 allows a server to pre-emptively send (or "push") responses
+     (along with corresponding "promised" requests) to a client in
+     association with a previous client-initiated request.  This can be
+     useful when the server knows the client will need to have those
+     responses available in order to fully process the response to the
+     original request.
+     - [RFC 7540](https://tools.ietf.org/html/rfc7540#section-8.2)
+
+API Platform leverages this capability by pushing relations of a resource to clients.
+
+```php
+<?php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiProperty;
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource
+ */
+class Book
+{
+    /**
+     * @var Author
+     * @ApiProperty(push=true)
+     */
+    public $author;
+}
+```
+
+By setting the `push` attribute to `true` on a property holding a relation, API Platform will automatically add a valid `Link` HTTP header with the `preload` relation.
+According to the [Preload W3C Candidate Recommendation](https://www.w3.org/TR/preload/), web servers and proxy servers can read this header, fetch the related resource and send it to the client using Server Push.
+[NGINX](https://www.nginx.com/blog/nginx-1-13-9-http2-server-push/), [Apache](https://httpd.apache.org/docs/current/howto/http2.html#push), [CloudFlare](https://www.cloudflare.com/website-optimization/http2/serverpush/), [Fastly](https://docs.fastly.com/guides/performance-tuning/http2-server-push) and [Akamai](https://blogs.akamai.com/2017/03/http2-server-push-the-what-how-and-why.html) honor this header. 
+
+Using this feature maximises HTTP cache hits for your API resources.
+For best performance, this feature should be used in conjunction with [the built-in HTTP cache invalidation system (based on Varnish)](performance.md#enabling-the-built-in-http-cache-invalidation-system).

core/serialization.md

@@ -296,6 +296,8 @@ In order to optimize such embedded relations, the default Doctrine data provider
 marked as [`EAGER`](http://doctrine-orm.readthedocs.io/projects/doctrine-orm/en/latest/reference/annotations-reference.html#manytoone).
 This avoids the need for extra queries to be executed when serializing the related objects.
 
+Instead of embedding relation in the main HTTP response, you may want [to "push" them to the client using HTTP/2 server push](push-relations.md).
+
 ### Denormalization
 
 It is also possible to embed a relation in `PUT` and `POST` requests. To enable that feature, set the serialization groups