Merge pull request Kinto#722 from Kinto/permission-capability

Add some documentation and capability for the permissions endpoint.

CHANGELOG.rst

@@ -6,7 +6,7 @@ This document describes changes between each past release.
 3.4.0 (unreleased)
 ==================
 
-- Nothing changed yet.
+- Add the ``permissions_endpoint`` capability. (#722)
 
 
 3.3.0 (2016-07-18)

docs/configuration/settings.rst

@@ -59,7 +59,12 @@ Feature settings
 +-------------------------------------------------+--------------+---------------------------------------------------------------------------+
 | kinto.experimental_collection_schema_validation | ``False``    | *Experimental*: Allow definition of JSON schema at the collection level,  |
 |                                                 |              | in order to :ref:`validate submitted records <collection-json-schema>`.   |
-|                                                 |              | It is marked as experimental because the API might subjet to changes.     |
+|                                                 |              | It is marked as experimental because the API might be subject to changes. |
++-------------------------------------------------+--------------+---------------------------------------------------------------------------+
+| kinto.experimental_permissions_endpoint         | ``False``    | *Experimental*: Add a new ``/permissions`` endpoint to let the user grab  |
+|                                                 |              | the list of objects (buckets, collections, groups, records) on which they |
+|                                                 |              | have read or write permission.                                            |
+|                                                 |              | It is marked as experimental because the API might be subject to changes. |
 +-------------------------------------------------+--------------+---------------------------------------------------------------------------+
 | kinto.trailing_slash_redirect_enabled           | ``True``     | Try to redirect resources removing slash or adding it for the root URL    |
 |                                                 |              | endpoint: ``/v1`` redirects to ``/v1/`` and ``/buckets/default/``         |
@@ -590,10 +595,27 @@ dangerous to leave on by default, and must therefore be enabled explicitly.
 
     kinto.flush_endpoint_enabled = true
 
-Then, issue a `POST` request to the `/__flush__` endpoint to flush all
+Then, issue a ``POST`` request to the ``/__flush__`` endpoint to flush all
 the data.
 
 
+Activating the permissions endpoint
+===================================
+
+
+The Permissions endpoint is used to get a list of all user accessible
+objects in the server as well as their permissions. It enables
+applications such as the kinto-admin to discover what the user is
+allowed to do and which data can be managed.
+
+.. code-block :: ini
+
+    kinto.permissions_endpoint_enabled = true
+
+Then, issue a ``GET`` request to the ``/permissions`` endpoint to get the
+list of the user permissions on the server ressources.
+
+
 .. _configuration-client-caching:
 
 Client caching

kinto/__init__.py

@@ -80,7 +80,14 @@ def main(global_config, config=None, **settings):
     permissions_endpoint_enabled = (
         asbool(settings['experimental_permissions_endpoint']) and
         hasattr(config.registry, 'permission'))
-    if not permissions_endpoint_enabled:
+    if permissions_endpoint_enabled:
+        config.add_api_capability(
+            "permissions_endpoint",
+            description="The permissions endpoint can be used to list all "
+                        "user objects permissions.",
+            url="https://kinto.readthedocs.io/en/latest/configuration/"
+                "settings.html#activating-the-permissions-endpoint")
+    else:
         kwargs.setdefault('ignore', []).append('kinto.views.permissions')
 
     config.scan("kinto.views", **kwargs)

kinto/tests/test_views_hello.py

@@ -67,3 +67,26 @@ def test_flush_capability_if_not_enabled(self):
         resp = app.get('/')
         capabilities = resp.json['capabilities']
         self.assertNotIn('flush_endpoint', capabilities)
+
+    def test_permissions_capability_if_enabled(self):
+        settings = self.get_app_settings()
+        settings['experimental_permissions_endpoint'] = True
+        app = self._get_test_app(settings=settings)
+        resp = app.get('/')
+        capabilities = resp.json['capabilities']
+        self.assertIn('permissions_endpoint', capabilities)
+        expected = {
+            "description": "The permissions endpoint can be used to list "
+                           "all user objects permissions.",
+            "url": "https://kinto.readthedocs.io/en/latest/configuration/"
+                   "settings.html#activating-the-permissions-endpoint"
+        }
+        self.assertEqual(expected, capabilities['permissions_endpoint'])
+
+    def test_permissions_capability_if_not_enabled(self):
+        settings = self.get_app_settings()
+        settings['experimental_permissions_endpoint'] = False
+        app = self._get_test_app(settings=settings)
+        resp = app.get('/')
+        capabilities = resp.json['capabilities']
+        self.assertNotIn('permissions_endpoint', capabilities)