Changes required for APIv3 in corporate

readthedocs/api/v3/mixins.py

@@ -3,6 +3,7 @@
 from rest_framework.response import Response
 
 from readthedocs.builds.models import Version
+from readthedocs.organizations.models import Organization
 from readthedocs.projects.models import Project
 
 
@@ -22,6 +23,11 @@ class NestedParentObjectMixin:
         'version__slug',
     ]
 
+    ORGANIZATION_LOOKUP_NAMES = [
+        'organization__slug',
+        'organizations__slug',
+    ]
+
     def _get_parent_object_lookup(self, lookup_names):
         query_dict = self.get_parents_query_dict()
         for lookup in lookup_names:
@@ -48,6 +54,19 @@ def _get_parent_version(self):
             project__slug=project_slug,
         )
 
+    def _get_parent_organization(self):
+        slug = self._get_parent_object_lookup(self.ORGANIZATION_LOOKUP_NAMES)
+
+        # when hitting ``/organizations/<slug>/`` we don't have a "parent" organization
+        # because this endpoint is the base one, so we just get the organization from
+        # ``organization_slug`` kwargs
+        slug = slug or self.kwargs.get('organization_slug')
+
+        return get_object_or_404(
+            Organization,
+            slug=slug,
+        )
+
 
 class ProjectQuerySetMixin(NestedParentObjectMixin):
 
@@ -103,6 +122,60 @@ def get_queryset(self):
         return self.listing_objects(queryset, self.request.user)
 
 
+class OrganizationQuerySetMixin(NestedParentObjectMixin):
+
+    """
+    Mixin to define queryset permissions for ViewSet only in one place.
+
+    All APIv3 organizations' ViewSet should inherit this mixin, unless specific permissions
+    required. In that case, a specific mixin for that case should be defined.
+    """
+
+    def detail_objects(self, queryset, user):
+        # Filter results by user
+        return queryset.for_user(user=user)
+
+    def listing_objects(self, queryset, user):
+        organization = self._get_parent_organization()
+        if self.has_admin_permission(user, organization):
+            return queryset
+
+        return queryset.none()
+
+    def has_admin_permission(self, user, organization):
+        # Use .only for small optimization
+        admin_organizations = self.admin_organizations(user).only('id')
+
+        if organization in admin_organizations:
+            return True
+
+        return False
+
+    def admin_organizations(self, user):
+        return Organization.objects.for_admin_user(user=user)
+
+    def get_queryset(self):
+        """
+        Filter results based on user permissions.
+
+        1. returns ``Organizations`` where the user is admin if ``/organizations/`` is hit
+        2. filters by parent ``organization_slug`` (NestedViewSetMixin)
+        2. returns ``detail_objects`` results if it's a detail view
+        3. returns ``listing_objects`` results if it's a listing view
+        4. raise a ``NotFound`` exception otherwise
+        """
+
+        # We need to have defined the class attribute as ``queryset = Model.objects.all()``
+        queryset = super().get_queryset()
+
+        # Detail requests are public
+        if self.detail:
+            return self.detail_objects(queryset, self.request.user)
+
+        # List view are only allowed if user is owner of parent project
+        return self.listing_objects(queryset, self.request.user)
+
+
 class UpdateMixin:
 
     """Make PUT to return 204 on success like PATCH does."""

readthedocs/api/v3/permissions.py

@@ -1,5 +1,21 @@
 from rest_framework.permissions import IsAuthenticated, BasePermission
 
+from readthedocs.core.utils.extend import SettingsOverrideObject
+
+
+class UserProjectsListing(BasePermission):
+
+    """Allow access to ``/projects`` (user's projects listing)."""
+
+    def has_permission(self, request, view):
+        if view.basename == 'projects' and any([
+                view.action == 'list',
+                view.action == 'create',  # used to create Form in BrowsableAPIRenderer
+                view.action is None,  # needed for BrowsableAPIRenderer
+        ]):
+            # hitting ``/projects/``, allowing
+            return True
+
 
 class PublicDetailPrivateListing(IsAuthenticated):
 
@@ -8,33 +24,22 @@ class PublicDetailPrivateListing(IsAuthenticated):
 
     * Always give permission for a ``detail`` request
     * Only give permission for ``listing`` request if user is admin of the project
-    * Allow access to ``/projects`` (user's projects listing)
     """
 
     def has_permission(self, request, view):
-        is_authenticated = super().has_permission(request, view)
-        if is_authenticated:
-            if view.basename == 'projects' and any([
-                    view.action == 'list',
-                    view.action == 'create',  # used to create Form in BrowsableAPIRenderer
-                    view.action is None,  # needed for BrowsableAPIRenderer
-            ]):
-                # hitting ``/projects/``, allowing
-                return True
-
-            # NOTE: ``superproject`` is an action name, defined by the class
-            # method under ``ProjectViewSet``. We should apply the same
-            # permissions restrictions than for a detail action (since it only
-            # returns one superproject if exists). ``list`` and ``retrieve`` are
-            # DRF standard action names (same as ``update`` or ``partial_update``).
-            if view.detail and view.action in ('list', 'retrieve', 'superproject'):
-                # detail view is only allowed on list/retrieve actions (not
-                # ``update`` or ``partial_update``).
-                return True
-
-            project = view._get_parent_project()
-            if view.has_admin_permission(request.user, project):
-                return True
+        # NOTE: ``superproject`` is an action name, defined by the class
+        # method under ``ProjectViewSet``. We should apply the same
+        # permissions restrictions than for a detail action (since it only
+        # returns one superproject if exists). ``list`` and ``retrieve`` are
+        # DRF standard action names (same as ``update`` or ``partial_update``).
+        if view.detail and view.action in ('list', 'retrieve', 'superproject'):
+            # detail view is only allowed on list/retrieve actions (not
+            # ``update`` or ``partial_update``).
+            return True
+
+        project = view._get_parent_project()
+        if view.has_admin_permission(request.user, project):
+            return True
 
         return False
 
@@ -47,3 +52,46 @@ def has_permission(self, request, view):
         project = view._get_parent_project()
         if view.has_admin_permission(request.user, project):
             return True
+
+
+class IsOrganizationAdmin(BasePermission):
+
+    def has_permission(self, request, view):
+        organization = view._get_parent_organization()
+        if view.has_admin_permission(request.user, organization):
+            return True
+
+
+class UserOrganizationsListing(BasePermission):
+
+    def has_permission(self, request, view):
+        if view.basename == 'organizations' and any([
+                view.action == 'list',
+                view.action is None,  # needed for BrowsableAPIRenderer
+        ]):
+            # hitting ``/organizations/``, allowing
+            return True
+
+
+class CommonPermissionsBase(BasePermission):
+
+    """
+    Common permission class used for most APIv3 endpoints.
+
+    This class should be used by ``APIv3Settings.permission_classes`` to define
+    the permissions for most APIv3 endpoints. It has to be overriden from
+    corporate to define proper permissions there.
+    """
+
+    def has_permission(self, request, view):
+        if not IsAuthenticated().has_permission(request, view):
+            return False
+
+        return (
+            UserProjectsListing().has_permission(request, view) or
+            PublicDetailPrivateListing().has_permission(request, view)
+        )
+
+
+class CommonPermissions(SettingsOverrideObject):
+    _default_class = CommonPermissionsBase

readthedocs/api/v3/serializers.py

@@ -10,14 +10,14 @@
 from rest_flex_fields.serializers import FlexFieldsSerializerMixin
 from rest_framework import serializers
 
+from readthedocs.core.utils.extend import SettingsOverrideObject
 from readthedocs.builds.models import Build, Version
 from readthedocs.core.utils import slugify
+from readthedocs.organizations.models import Organization, Team
 from readthedocs.projects.constants import (
     LANGUAGES,
     PROGRAMMING_LANGUAGES,
     REPO_CHOICES,
-    PRIVACY_CHOICES,
-    PROTECTED,
 )
 from readthedocs.projects.models import Project, EnvironmentVariable, ProjectRelationship
 from readthedocs.redirects.models import Redirect, TYPE_CHOICES as REDIRECT_TYPE_CHOICES
@@ -433,7 +433,7 @@ def get_translations(self, obj):
         return self._absolute_url(path)
 
 
-class ProjectCreateSerializer(FlexFieldsModelSerializer):
+class ProjectCreateSerializerBase(FlexFieldsModelSerializer):
 
     """Serializer used to Import a Project."""
 
@@ -459,7 +459,11 @@ def validate_name(self, value):
         return value
 
 
-class ProjectUpdateSerializer(FlexFieldsModelSerializer):
+class ProjectCreateSerializer(SettingsOverrideObject):
+    _default_class = ProjectCreateSerializerBase
+
+
+class ProjectUpdateSerializerBase(FlexFieldsModelSerializer):
 
     """Serializer used to modify a Project once imported."""
 
@@ -492,7 +496,11 @@ class Meta:
         )
 
 
-class ProjectSerializer(FlexFieldsModelSerializer):
+class ProjectUpdateSerializer(SettingsOverrideObject):
+    _default_class = ProjectUpdateSerializerBase
+
+
+class ProjectSerializerBase(FlexFieldsModelSerializer):
 
     homepage = serializers.SerializerMethodField()
     language = LanguageSerializer()
@@ -567,6 +575,10 @@ def get_subproject_of(self, obj):
             return None
 
 
+class ProjectSerializer(SettingsOverrideObject):
+    _default_class = ProjectSerializerBase
+
+
 class SubprojectCreateSerializer(FlexFieldsModelSerializer):
 
     """Serializer used to define a Project as subproject of another Project."""
@@ -800,3 +812,73 @@ class Meta:
             'project',
             '_links',
         ]
+
+
+class OrganizationLinksSerializer(BaseLinksSerializer):
+    _self = serializers.SerializerMethodField()
+    projects = serializers.SerializerMethodField()
+
+    def get__self(self, obj):
+        path = reverse(
+            'organizations-detail',
+            kwargs={
+                'organization_slug': obj.slug,
+            })
+        return self._absolute_url(path)
+
+    def get_projects(self, obj):
+        path = reverse(
+            'organizations-projects-list',
+            kwargs={
+                'parent_lookup_organizations__slug': obj.slug,
+            },
+        )
+        return self._absolute_url(path)
+
+
+class TeamSerializer(serializers.ModelSerializer):
+
+    # TODO: add ``projects`` as flex field when we have a
+    # /organizations/<slug>/teams/<slug>/projects endpoint
+
+    created = serializers.DateTimeField(source='pub_date')
+    modified = serializers.DateTimeField(source='modified_date')
+
+    class Meta:
+        model = Team
+        fields = (
+            'name',
+            'slug',
+            'created',
+            'modified',
+            'access',
+        )
+
+
+class OrganizationSerializer(FlexFieldsModelSerializer):
+
+    created = serializers.DateTimeField(source='pub_date')
+    modified = serializers.DateTimeField(source='modified_date')
+    owners = UserSerializer(many=True)
+
+    _links = OrganizationLinksSerializer(source='*')
+
+    class Meta:
+        model = Organization
+        fields = (
+            'name',
+            'description',
+            'url',
+            'slug',
+            'email',
+            'owners',
+            'created',
+            'modified',
+            'disabled',
+            '_links',
+        )
+
+        expandable_fields = {
+            'projects': (ProjectSerializer, {'many': True}),
+            'teams': (TeamSerializer, {'many': True}),
+        }

readthedocs/api/v3/tests/mixins.py

@@ -153,8 +153,9 @@ def _create_subproject(self):
         )
         self.project_relationship = self.project.add_subproject(self.subproject)
 
-    def _get_response_dict(self, view_name):
-        filename = Path(__file__).absolute().parent / 'responses' / f'{view_name}.json'
+    def _get_response_dict(self, view_name, filepath=None):
+        filepath = filepath or __file__
+        filename = Path(filepath).absolute().parent / 'responses' / f'{view_name}.json'
         return json.load(open(filename))
 
     def assertDictEqual(self, d1, d2):