.../Compiler/RemoveJsonapiFormatCompilerPass.php   | 29 +++++++++++++++++-----
 src/JsonapiServiceProvider.php                     |  2 +-
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/src/DependencyInjection/Compiler/RemoveJsonapiFormatCompilerPass.php b/src/DependencyInjection/Compiler/RemoveJsonapiFormatCompilerPass.php
index c3a7ee5..50add4c 100644
--- a/src/DependencyInjection/Compiler/RemoveJsonapiFormatCompilerPass.php
+++ b/src/DependencyInjection/Compiler/RemoveJsonapiFormatCompilerPass.php
@@ -2,19 +2,36 @@
 
 namespace Drupal\jsonapi\DependencyInjection\Compiler;
 
-use Drupal\serialization\RegisterSerializationClassesCompilerPass;
-use Symfony\Component\DependencyInjection\Reference;
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 
 /**
- * Adds services tagged 'normalizer' to the JSON API Serializer.
+ * Removes 'api_json' format from the 'serializer.formats' container parameter.
+ *
+ * We want the 'api_json' format to not be supported in the REST module. But the
+ * JSON API module also should not have to define al alternative 'serializer'
+ * service.
+ * This is achieved through removing the 'api_json' format from the
+ * 'serializer.formats' container parameter. The consequences of doing that:
+ *
+ * - the REST module no longer allows this format to be used
+ * - the 'serialization.exception.default' service does not support 'api_json',
+ *   hence a custom exception subscriber is needed, which this module has:
+ *   'jsonapi.exception_subscriber'
+ * - the 'serializer' service does support 'api_json'
+ *
+ * In other words: the 'serializer' service supports 'api_json', but nothing is
+ * aware of it. You could only know by calling 'serializer:supportsEncoding()'.
  *
  * @see \Drupal\serialization\RegisterSerializationClassesCompilerPass
+ * @see \Drupal\jsonapi\JsonapiServiceProvider::register()
+ * @see \Drupal\jsonapi\EventSubscriber\DefaultExceptionSubscriber
+ * @see \Drupal\Tests\jsonapi\Functional\RestJsonApiUnsupported
  */
-class RemoveJsonapiFormatCompilerPass extends RegisterSerializationClassesCompilerPass {
+class RemoveJsonapiFormatCompilerPass implements CompilerPassInterface {
 
   /**
-   * Adds services to the Serializer.
+   * Updates the 'serializer.formats' container p
    *
    * @param \Symfony\Component\DependencyInjection\ContainerBuilder $container
    *   The container to process.
@@ -24,7 +41,7 @@ class RemoveJsonapiFormatCompilerPass extends RegisterSerializationClassesCompil
       $filtered_formats = array_filter(
         $container->getParameter('serializer.formats'),
         function ($format) {
-          return $format != 'api_json';
+          return $format !== 'api_json';
         }
       );
       $container->setParameter('serializer.formats', array_values($filtered_formats));
diff --git a/src/JsonapiServiceProvider.php b/src/JsonapiServiceProvider.php
index bd4f852..f801059 100644
--- a/src/JsonapiServiceProvider.php
+++ b/src/JsonapiServiceProvider.php
@@ -9,7 +9,7 @@ use Drupal\jsonapi\DependencyInjection\Compiler\RemoveJsonapiFormatCompilerPass;
 use Symfony\Component\DependencyInjection\Compiler\PassConfig;
 
 /**
- * Adds api_json as known format.
+ * Adds 'api_json' as known format and prevents its use in the REST module.
  *
  * @internal
  */