Wagtail 8: Make API v3 opt-in (#289)

* Make API v3 opt-in
   via the new `ENABLE_API_V3` setting

Author: zerolab

README.md

@@ -70,6 +70,7 @@ WAGTAILMEDIA = {
         "ogv",
         "webm",
     ],  # list of extensions
+    "ENABLE_API_V3": False,  # Wagtail 8.0+ - enable the v3 API endpoints
 }
 ```
 
@@ -285,6 +286,8 @@ class BlogPage(Page):
 
 ### API
 
+#### v2
+
 To expose media items in the API, you can follow the [Wagtail documentation guide](https://docs.wagtail.org/en/stable/advanced_topics/api/v2/configuration.html#api-v2-configuration)
 for API configuration with wagtailmedia specifics:
 
@@ -300,9 +303,16 @@ api_router = WagtailAPIRouter("wagtailapi")
 api_router.register_endpoint("media", MediaAPIViewSet)
 ```
 
+#### v3 (preview)
+
+Starting with version 8.0, Wagtail provides an [experimental API v3](https://docs.wagtail.org/en/stable/advanced_topics/api/v3/index.html), powered by [django-ninja](https://github.com/vitalik/django-ninja).
+To opt-in, set `ENABLE_API_V3` to `True` in the `WAGTAILMEDIA` setting. The wagtailmedia endpoint will be available under the `<v3 API root>/media/`.
+
+For further details, explore the [Wagtail API v3 documentation](https://docs.wagtail.org/en/stable/advanced_topics/api/v3/index.html).
+
 ## Translations
 
-wagtailmedia has translations in French and Chinese. More translations welcome!
+wagtailmedia has translations in Chinese, French, German, Romanian, Ukrainian. More translations welcome!
 
 ## Contributing
 

src/wagtailmedia/apps.py

@@ -32,13 +32,16 @@ def ready(self):
         )
 
         if WAGTAIL_VERSION >= (8, 0):
-            # v3 API. Note: the import order matters
-            from .api.v3.registry import register_content_types
+            from .settings import wagtailmedia_settings
 
-            register_content_types()
+            if wagtailmedia_settings.ENABLE_API_V3:
+                # v3 API. Note: the import order matters
+                from .api.v3.registry import register_content_types
 
-            from wagtail.api.v3.api import api
+                register_content_types()
 
-            from .api.v3.router import router
+                from wagtail.api.v3.api import api
 
-            api.add_router("/media/", router)
+                from .api.v3.router import router
+
+                api.add_router("/media/", router)

src/wagtailmedia/settings.py

@@ -31,6 +31,7 @@
         "ogv",
         "webm",
     ],
+    "ENABLE_API_V3": False,
 }
 
 # List of settings that have been deprecated

tests/test_api_v3/test_api_is_optin.py

@@ -0,0 +1,31 @@
+from wagtail import VERSION as WAGTAIL_VERSION
+
+
+if WAGTAIL_VERSION >= (8, 0):
+    from unittest import skipIf
+
+    from django.conf import settings
+    from django.urls import NoReverseMatch, reverse
+    from wagtail.api.v3.registry import registry
+
+    from wagtailmedia import get_media_model
+
+    from .base import TestV3MediaBase
+
+    Media = get_media_model()
+
+    @skipIf(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=True")
+    class TestAPIv3IsOptIn(TestV3MediaBase):
+        def test_schema_not_registered(self):
+            registration = registry.get(Media._meta.label)
+            self.assertIsNone(registration)
+
+        def test_schema_discovery_endpoint_doesnt_list_media(self):
+            self.login()
+            response = self.client.get(reverse("wagtailapi_v3:list_schemas"))
+            names = [entry["name"] for entry in response.json()["types"]]
+            self.assertNotIn(Media._meta.label, names)
+
+        def test_route_not_registered(self):
+            with self.assertRaises(NoReverseMatch):
+                reverse("wagtailapi_v3:list_media")

tests/test_api_v3/test_create.py

@@ -2,8 +2,9 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
-    from unittest import mock
+    from unittest import mock, skipUnless
 
+    from django.conf import settings
     from django.core.files.uploadedfile import SimpleUploadedFile
     from django.db.models.signals import post_save
     from django.test import override_settings
@@ -16,6 +17,7 @@
     Media = get_media_model()
     FILE_CONTENTS = b"Test media contents"
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     class TestV3MediaCreate(TestV3MediaBase):
         def post_media(self, **kwargs):
             data = {

tests/test_api_v3/test_custom_media_model.py

@@ -2,8 +2,10 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
+    from unittest import skipUnless
     from unittest.mock import patch
 
+    from django.conf import settings
     from django.contrib.auth.models import Group, Permission
     from django.core.files.uploadedfile import SimpleUploadedFile
     from django.test import TestCase, override_settings
@@ -19,6 +21,7 @@
     from wagtailmedia.api.v3.form_data import build_media_form
     from wagtailmedia.forms import get_media_form
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     @override_settings(WAGTAILMEDIA={"MEDIA_MODEL": "wagtailmedia_tests.CustomMedia"})
     class TestV3CustomMediaModel(WagtailTestUtils, TestCase):
         @classmethod

tests/test_api_v3/test_delete.py

@@ -2,8 +2,9 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
-    from unittest import mock
+    from unittest import mock, skipUnless
 
+    from django.conf import settings
     from django.db.models.signals import post_delete
     from django.urls import reverse
 
@@ -13,6 +14,7 @@
 
     Media = get_media_model()
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     class TestV3MediaDelete(TestV3MediaBase):
         def delete(self, media_id):
             return self.client.delete(

tests/test_api_v3/test_detail.py

@@ -2,11 +2,15 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
+    from unittest import skipUnless
+
+    from django.conf import settings
     from django.urls import reverse
     from wagtail.models import CollectionViewRestriction
 
     from .base import TestV3MediaBase
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     class TestV3MediaDetail(TestV3MediaBase):
         def get_response(self, media_id):
             return self.client.get(

tests/test_api_v3/test_listing.py

@@ -2,6 +2,9 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
+    from unittest import skipUnless
+
+    from django.conf import settings
     from django.contrib.auth.models import Group
     from django.db import connection
     from django.test.utils import CaptureQueriesContext
@@ -10,6 +13,7 @@
 
     from .base import TestV3MediaBase
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     class TestV3MediaListing(TestV3MediaBase):
         def get_response(self, **params):
             return self.client.get(reverse("wagtailapi_v3:list_media"), params)

tests/test_api_v3/test_schemas.py

@@ -2,6 +2,9 @@
 
 
 if WAGTAIL_VERSION >= (8, 0):
+    from unittest import skipUnless
+
+    from django.conf import settings
     from django.urls import reverse
     from wagtail.api.v3.registry import registry
 
@@ -12,6 +15,7 @@
 
     Media = get_media_model()
 
+    @skipUnless(settings.ENABLE_API_V3, "Skipped as testing with ENABLE_API_V3=False")
     class TestV3MediaSchemas(TestV3MediaBase):
         def test_content_type_registered_for_schema_discovery(self):
             registration = registry.get(Media._meta.label)