Normalizers and REST responses now support explicit cacheability bubbling

In Drupal 8.5.0, normalizers can now bubble cacheability metadata explicitly, rather than needing to bubble cacheability metadata onto the global render context (which is really leaking):

use Drupal\serialization\Normalizer\CacheableNormalizerInterface;

public function normalize($object, $format = NULL, array $context = []) {
  …

  if (isset($context[CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY])) {
    $context[CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY]->addCacheableDependency(…)
  }

  …
}

Example

For example, in the case of the HAL normalization, all relation and type links (in a HAL normalization's _links section) use an absolute URL that depends on the current site's URL. Therefore all HAL responses actually vary by the url.site cache context. But there was no way to associate this cacheability metadata. Now there is:

Before

protected function getLinkDomain() {
  …
  return $request->getSchemeAndHttpHost() . $request->getBasePath();
…
}

After

protected function getLinkDomain(array $context = []) {
  …
  if (isset($context[CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY])) {
    $context[CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY]->addCacheContexts(['url.site']);
  }
  return $request->getSchemeAndHttpHost() . $request->getBasePath();
…
}

This means that the response can now safely and correctly be cached by Dynamic Page Cache.