Merge branch 'clean_api_duplicate' into 'master'

Refactor API

Closes #128

See merge request federez/re2o!172

CHANGELOG.md

@@ -38,7 +38,7 @@ mkdir -p media/images
 ## MR 163: Fix install re2o
 
 Refactored install_re2o.sh script.
-* There are more tools available with it but some fucntion have changed, report to [the dedicated wiki page](for more informations) or run:
+* There are more tools available with it but some function have changed, report to [the dedicated wiki page](https://gitlab.federez.net/federez/re2o/wikis/User%20Documentation/Setup%20script)for more informations or run:
 ```
 install_re2o.sh help
 ```
@@ -53,3 +53,22 @@ Add the logo and fix somme issues on the navbar and home page. Only collecting t
 python3 manage.py collectstatic
 ```
 
+
+## MR 172: Refactor API
+
+Creates a new (nearly) REST API to expose all models of Re2o. See [the dedicated wiki page](https://gitlab.federez.net/federez/re2o/wikis/API/Raw-Usage) for more details on how to use it.
+* For testing purpose, add `volatildap` package:
+```
+pip3 install volatildap
+```
+* Activate HTTP Authorization passthrough in by adding the following in `/etc/apache2/site-available/re2o.conf` (example in `install_utils/apache2/re2o.conf`):
+```
+    WSGIPassAuthorization On
+```
+* Activate the API if you want to use it by adding `'api'` to the optional apps in `re2o/settings_local.py`:
+```
+OPTIONAL_APPS = (
+    ...
+    'api',
+    ...
+)
\ No newline at end of file

api/acl.py

+# Re2o est un logiciel d'administration développé initiallement au rezometz. Il
+# se veut agnostique au réseau considéré, de manière à être installable en
+# quelques clics.
+#
+# Copyright © 2018 Maël Kervella
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""Defines the ACL for the whole API.
+
+Importing this module, creates the 'can view api' permission if not already
+done.
+"""
+
+from django.conf import settings
+from django.contrib.contenttypes.models import ContentType
+from django.contrib.auth.models import Permission
+from django.utils.translation import ugettext_lazy as _
+
+
+def _create_api_permission():
+    """Creates the 'use_api' permission if not created.
+    
+    The 'use_api' is a fake permission in the sense it is not associated with an
+    existing model and this ensure the permission is created every time this file
+    is imported.
+    """
+    api_content_type, created = ContentType.objects.get_or_create(
+        app_label=settings.API_CONTENT_TYPE_APP_LABEL,
+        model=settings.API_CONTENT_TYPE_MODEL
+    )
+    if created:
+        api_content_type.save()
+    api_permission, created = Permission.objects.get_or_create(
+        name=settings.API_PERMISSION_NAME,
+        content_type=api_content_type,
+        codename=settings.API_PERMISSION_CODENAME
+    )
+    if created:
+        api_permission.save()
+
+
+_create_api_permission()
+
+
+def can_view(user):
+    """Check if an user can view the application.
+
+    Args:
+        user: The user who wants to view the application.
+
+    Returns:
+        A couple (allowed, msg) where allowed is a boolean which is True if
+        viewing is granted and msg is a message (can be None).
+    """
+    kwargs = {
+        'app_label': settings.API_CONTENT_TYPE_APP_LABEL,
+        'codename': settings.API_PERMISSION_CODENAME
+    }
+    can = user.has_perm('%(app_label)s.%(codename)s' % kwargs)
+    return can, None if can else _("You cannot see this application.")

api/authentication.py

+# Re2o est un logiciel d'administration développé initiallement au rezometz. Il
+# se veut agnostique au réseau considéré, de manière à être installable en
+# quelques clics.
+#
+# Copyright © 2018 Maël Kervella
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""Defines the authentication classes used in the API to authenticate a user.
+"""
+
+import datetime
+
+from django.conf import settings
+from django.utils.translation import ugettext_lazy as _
+from rest_framework.authentication import TokenAuthentication
+from rest_framework import exceptions
+
+class ExpiringTokenAuthentication(TokenAuthentication):
+    """Authenticate a user if the provided token is valid and not expired.
+    """
+    def authenticate_credentials(self, key):
+        """See base class. Add the verification the token is not expired.
+        """
+        base = super(ExpiringTokenAuthentication, self)
+        user, token = base.authenticate_credentials(key)
+
+        # Check that the genration time of the token is not too old
+        token_duration = datetime.timedelta(
+            seconds=settings.API_TOKEN_DURATION
+        )
+        utc_now = datetime.datetime.now(datetime.timezone.utc)
+        if token.created < utc_now - token_duration:
+            raise exceptions.AuthenticationFailed(_('Token has expired'))
+
+        return (token.user, token)

api/pagination.py

+# Re2o est un logiciel d'administration développé initiallement au rezometz. Il
+# se veut agnostique au réseau considéré, de manière à être installable en
+# quelques clics.
+#
+# Copyright © 2018 Maël Kervella
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""Defines the pagination classes used in the API to paginate the results.
+"""
+
+from rest_framework import pagination
+
+
+class PageSizedPagination(pagination.PageNumberPagination):
+    """Provide the possibility to control the page size by using the
+    'page_size' parameter. The value 'all' can be used for this parameter
+    to retrieve all the results in a single page.
+
+    Attributes:
+        page_size_query_param: The string to look for in the parameters of
+            a query to get the page_size requested.
+        all_pages_strings: A set of strings that can be used in the query to
+            request all results in a single page.
+        max_page_size: The maximum number of results a page can output no
+            matter what is requested.
+    """
+    page_size_query_param = 'page_size'
+    all_pages_strings = ('all',)
+    max_page_size = 10000
+
+    def get_page_size(self, request):
+        """Retrieve the size of the page according to the parameters of the
+        request.
+
+        Args:
+            request: the request of the user
+
+        Returns:
+            A integer between 0 and `max_page_size` that represent the size
+            of the page to use.
+        """
+        try:
+            page_size_str = request.query_params[self.page_size_query_param]
+            if page_size_str in self.all_pages_strings:
+                return self.max_page_size
+        except KeyError:
+            pass
+
+        return super(PageSizedPagination, self).get_page_size(request)

api/permissions.py

+# Re2o est un logiciel d'administration développé initiallement au rezometz. Il
+# se veut agnostique au réseau considéré, de manière à être installable en
+# quelques clics.
+#
+# Copyright © 2018 Maël Kervella
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""Defines the permission classes used in the API.
+"""
+
+from rest_framework import permissions, exceptions
+
+from re2o.acl import can_create, can_edit, can_delete, can_view_all
+
+from . import acl
+
+
+def can_see_api(*_, **__):
+    """Check if a user can view the API.
+
+    Returns:
+        A function that takes a user as an argument and returns
+        an ACL tuple that assert this user can see the API.
+    """
+    return lambda user: acl.can_view(user)
+
+
+def _get_param_in_view(view, param_name):
+    """Utility function to retrieve an attribute in a view passed in argument.
+
+    Uses the result of `{view}.get_{param_name}()` if existing else uses the
+    value of `{view}.{param_name}` directly.
+
+    Args:
+        view: The view where to look into.
+        param_name: The name of the attribute to look for.
+
+    Returns:
+        The result of the getter function if found else the value of the
+        attribute itself.
+
+    Raises:
+        AssertionError: None of the getter function or the attribute are
+            defined in the view.
+    """
+    assert hasattr(view, 'get_'+param_name) \
+        or getattr(view, param_name, None) is not None, (
+        'cannot apply {} on a view that does not set '
+        '`.{}` or have a `.get_{}()` method.'
+    ).format(self.__class__.__name__, param_name, param_name)
+
+    if hasattr(view, 'get_'+param_name):
+        param = getattr(view, 'get_'+param_name)()
+        assert param is not None, (
+            '{}.get_{}() returned None'
+        ).format(view.__class__.__name__, param_name)
+        return param
+    return getattr(view, param_name)
+
+
+class ACLPermission(permissions.BasePermission):
+    """A permission class used to check the ACL to validate the permissions
+    of a user.
+
+    The view must define a `.get_perms_map()` or a `.perms_map` attribute.
+    See the wiki for the syntax of this attribute.
+    """
+
+    def get_required_permissions(self, method, view):
+        """Build the list of permissions required for the request to be
+        accepted.
+
+        Args:
+            method: The HTTP method name used for the request.
+            view: The view which is responding to the request.
+
+        Returns:
+            The list of ACL functions to apply to a user in order to check
+            if he has the right permissions.
+
+        Raises:
+            AssertionError: None of `.get_perms_map()` or `.perms_map` are
+                defined in the view.
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        perms_map = _get_param_in_view(view, 'perms_map')
+
+        if method not in perms_map:
+            raise exceptions.MethodNotAllowed(method)
+
+        return [can_see_api()] + list(perms_map[method])
+
+    def has_permission(self, request, view):
+        """Check that the user has the permissions to perform the request.
+
+        Args:
+            request: The request performed.
+            view: The view which is responding to the request.
+
+        Returns:
+            A boolean indicating if the user has the permission to
+            perform the request.
+
+        Raises:
+            AssertionError: None of `.get_perms_map()` or `.perms_map` are
+                defined in the view.
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        # Workaround to ensure ACLPermissions are not applied
+        # to the root view when using DefaultRouter.
+        if getattr(view, '_ignore_model_permissions', False):
+            return True
+
+        if not request.user or not request.user.is_authenticated:
+            return False
+
+        perms = self.get_required_permissions(request.method, view)
+
+        return all(perm(request.user)[0] for perm in perms)
+
+
+class AutodetectACLPermission(permissions.BasePermission):
+    """A permission class used to autodetect the ACL needed to validate the
+    permissions of a user based on the queryset of the view.
+
+    The view must define a `.get_queryset()` or a `.queryset` attribute.
+
+    Attributes:
+        perms_map: The mapping of each valid HTTP method to the required
+            model-based ACL permissions.
+        perms_obj_map: The mapping of each valid HTTP method to the required
+            object-based ACL permissions.
+    """
+
+    perms_map = {
+        'GET': [can_see_api, lambda model: model.can_view_all],
+        'OPTIONS': [can_see_api, lambda model: model.can_view_all],
+        'HEAD': [can_see_api, lambda model: model.can_view_all],
+        'POST': [can_see_api, lambda model: model.can_create],
+        'PUT': [],     # No restrictions, apply to objects
+        'PATCH': [],   # No restrictions, apply to objects
+        'DELETE': [],  # No restrictions, apply to objects
+    }
+    perms_obj_map = {
+        'GET': [can_see_api, lambda obj: obj.can_view],
+        'OPTIONS': [can_see_api, lambda obj: obj.can_view],
+        'HEAD': [can_see_api, lambda obj: obj.can_view],
+        'POST': [],    # No restrictions, apply to models
+        'PUT': [can_see_api, lambda obj: obj.can_edit],
+        'PATCH': [can_see_api, lambda obj: obj.can_edit],
+        'DELETE': [can_see_api, lambda obj: obj.can_delete],
+    }
+
+    def get_required_permissions(self, method, model):
+        """Build the list of model-based permissions required for the
+        request to be accepted.
+
+        Args:
+            method: The HTTP method name used for the request.
+            view: The view which is responding to the request.
+
+        Returns:
+            The list of ACL functions to apply to a user in order to check
+            if he has the right permissions.
+
+        Raises:
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        if method not in self.perms_map:
+            raise exceptions.MethodNotAllowed(method)
+
+        return [perm(model) for perm in self.perms_map[method]]
+
+    def get_required_object_permissions(self, method, obj):
+        """Build the list of object-based permissions required for the
+        request to be accepted.
+
+        Args:
+            method: The HTTP method name used for the request.
+            view: The view which is responding to the request.
+
+        Returns:
+            The list of ACL functions to apply to a user in order to check
+            if he has the right permissions.
+
+        Raises:
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        if method not in self.perms_obj_map:
+            raise exceptions.MethodNotAllowed(method)
+
+        return [perm(obj) for perm in self.perms_obj_map[method]]
+
+    def _queryset(self, view):
+        return _get_param_in_view(view, 'queryset')
+
+    def has_permission(self, request, view):
+        """Check that the user has the model-based permissions to perform
+        the request.
+
+        Args:
+            request: The request performed.
+            view: The view which is responding to the request.
+
+        Returns:
+            A boolean indicating if the user has the permission to
+            perform the request.
+
+        Raises:
+            AssertionError: None of `.get_queryset()` or `.queryset` are
+                defined in the view.
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        # Workaround to ensure ACLPermissions are not applied
+        # to the root view when using DefaultRouter.
+        if getattr(view, '_ignore_model_permissions', False):
+            return True
+
+        if not request.user or not request.user.is_authenticated:
+            return False
+
+        queryset = self._queryset(view)
+        perms = self.get_required_permissions(request.method, queryset.model)
+
+        return all(perm(request.user)[0] for perm in perms)
+
+    def has_object_permission(self, request, view, obj):
+        """Check that the user has the object-based permissions to perform
+        the request.
+
+        Args:
+            request: The request performed.
+            view: The view which is responding to the request.
+
+        Returns:
+            A boolean indicating if the user has the permission to
+            perform the request.
+
+        Raises:
+            rest_framework.exception.MethodNotAllowed: The requested method
+                is not allowed for this view.
+        """
+        # authentication checks have already executed via has_permission
+        user = request.user
+
+        perms = self.get_required_object_permissions(request.method, obj)
+
+        if not all(perm(request.user)[0] for perm in perms):
+            # If the user does not have permissions we need to determine if
+            # they have read permissions to see 403, or not, and simply see
+            # a 404 response.
+
+            if request.method in SAFE_METHODS:
+                # Read permissions already checked and failed, no need
+                # to make another lookup.
+                raise Http404
+
+            read_perms = self.get_required_object_permissions('GET', obj)
+            if not read_perms(request.user)[0]:
+                raise Http404
+
+            # Has read permissions.
+            return False
+
+        return True
+

api/routers.py

+# Re2o est un logiciel d'administration développé initiallement au rezometz. Il
+# se veut agnostique au réseau considéré, de manière à être installable en
+# quelques clics.
+#
+# Copyright © 2018 Mael Kervella
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+"""Defines the custom routers to generate the URLs of the API.
+"""
+
+from collections import OrderedDict
+
+from django.conf.urls import url, include
+from django.core.urlresolvers import NoReverseMatch
+from rest_framework import views
+from rest_framework.routers import DefaultRouter
+from rest_framework.response import Response
+from rest_framework.reverse import reverse
+from rest_framework.schemas import SchemaGenerator
+from rest_framework.settings import api_settings
+
+
+class AllViewsRouter(DefaultRouter):
+    """A router that can register both viewsets and views and generates
+    a full API root page with all the generated URLs.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.view_registry = []
+        super(AllViewsRouter, self).__init__(*args, **kwargs)
+
+    def register_viewset(self, *args, **kwargs):
+        """Register a viewset in the router. Alias of `register` for
+        convenience.
+
+        See `register` in the base class for details.
+        """
+        return self.register(*args, **kwargs)
+
+    def register_view(self, pattern, view, name=None):
+        """Register a view in the router.
+
+        Args:
+            pattern: The URL pattern to use for this view.
+            view: The class-based view to register.
+            name: An optional name for the route generated. Defaults is
+                based on the pattern last section (delimited by '/').
+        """
+        if name is None:
+            name = self.get_default_name(pattern)
+        self.view_registry.append((pattern, view, name))
+
+    def get_default_name(self, pattern):
+        """Returns the name to use for the route if none was specified.
+
+        Args:
+            pattern: The pattern for this route.
+
+        Returns:
+            The name to use for this route.
+        """
+        return pattern.split('/')[-1]
+
+    def get_api_root_view(self, schema_urls=None):
+        """Create a class-based view to use as the API root.
+
+        Highly inspired by the base class. See details on the implementation
+        in the base class. The only difference is that registered view URLs
+        are added after the registered viewset URLs on this root API page.
+
+        Args:
+            schema_urls: A schema to use for the URLs.
+
+        Returns:
+            The view to use to display the root API page.
+        """
+        api_root_dict = OrderedDict()
+        list_name = self.routes[0].name
+        for prefix, viewset, basename in self.registry:
+            api_root_dict[prefix] = list_name.format(basename=basename)
+        for pattern, view, name in self.view_registry:
+            api_root_dict[pattern] = name
+
+        view_renderers = list(api_settings.DEFAULT_RENDERER_CLASSES)
+        schema_media_types = []
+
+        if schema_urls and self.schema_title:
+            view_renderers += list(self.schema_renderers)
+            schema_generator = SchemaGenerator(
+                title=self.schema_title,
+                patterns=schema_urls
+            )
+            schema_media_types = [
+                renderer.media_type
+                for renderer in self.schema_renderers
+            ]
+
+        class APIRoot(views.APIView):
+            _ignore_model_permissions = True
+            renderer_classes = view_renderers
+
+            def get(self, request, *args, **kwargs):
+                if request.accepted_renderer.media_type in schema_media_types:
+                    # Return a schema response.
+                    schema = schema_generator.get_schema(request)
+                    if schema is None:
+                        raise exceptions.PermissionDenied()
+                    return Response(schema)
+
+                # Return a plain {"name": "hyperlink"} response.
+                ret = OrderedDict()
+                namespace = request.resolver_match.namespace
+                for key, url_name in api_root_dict.items():
+                    if namespace:
+                        url_name = namespace + ':' + url_name
+                    try:
+                        ret[key] = reverse(
+                            url_name,
+                            args=args,
+                            kwargs=kwargs,
+                            request=request,
+                            format=kwargs.get('format', None)
+                        )
+                    except NoReverseMatch:
+                        # Don't bail out if eg. no list routes exist, only detail routes.
+                        continue
+
+                return Response(ret)
+
+        return APIRoot.as_view()
+
+    def get_urls(self):
+        """Builds the list of URLs to register.
+
+        Returns:
+            A list of the URLs generated based on the viewsets registered