From 56f7dac9084f971c005f134c9d63b25a4f29ca2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20HUBSCHER?= Date: Thu, 16 Jul 2015 17:16:54 +0200 Subject: [PATCH 1/3] Add documentation about permissions handling using the API. --- docs/api/index.rst | 1 + docs/api/permissions.rst | 521 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 522 insertions(+) create mode 100644 docs/api/permissions.rst diff --git a/docs/api/index.rst b/docs/api/index.rst index 48edf5f15..869ef26d9 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -10,6 +10,7 @@ The HTTP APIs collections records groups + permissions See `cliquet API documentation `_ diff --git a/docs/api/permissions.rst b/docs/api/permissions.rst new file mode 100644 index 000000000..f81d4dddf --- /dev/null +++ b/docs/api/permissions.rst @@ -0,0 +1,521 @@ +.. _permissions-api: + +Permissions +########### + +Before to start, make sure to have read the :ref:`Understanding +permissions ` paragraph. + +Permissions can be added on any manipulated objects (:ref:`buckets +`, :ref:`groups `, :ref:`collections `, +:ref:`records `) + +By default the creator of an object grab write privileges on this +object. + + +How do I get my Kinto user id? +============================== + +To be able to add permissions for a user, the user id is needed. + +The user id can be found by calling the ``/`` endpoint logged. + +.. code-block:: + :emphasize-lines: 16 + + $ http GET http://localhost:8888/v1/ --auth user:pass + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Content-Length: 288 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 09:48:47 GMT + Server: waitress + + { + "documentation": "https://kinto.readthedocs.org/", + "hello": "cloud storage", + "settings": { + "cliquet.batch_max_requests": 25 + }, + "url": "http://localhost:8888/v1/", + "userid": "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6", + "version": "1.4.0" + } + + +In this case the user id is: ``basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6`` + +.. note:: + + In case of sharing, users may need to register their user id + associated with their email address for other user to add permission + to them. + + +Object permissions +================== + +On each object, it is possible to add ``write`` and ``read`` +permissions as well as ``sub-object:create`` ones. + +.. note:: + + In Kinto, object inherit their parents ones. i.e: giving the read + permission to a user on a bucket gives read permissions on all + objects stored in the bucket. + + +For instance, we can look at our own bucket permissions. + +.. code-block:: + + $ http GET http://localhost:8888/v1/buckets/default --auth user:pass + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Last-Modified, ETag + Content-Length: 187 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 09:59:30 GMT + Etag: "1437040770742" + Last-Modified: Thu, 16 Jul 2015 09:59:30 GMT + Server: waitress + + { + "data": { + "id": "46524be8-0ad7-3ac6-e260-71f8993feffa", + "last_modified": 1437040770742 + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + + +We can look at our own tasks collections permissions. + +.. code-block:: + + $ http GET http://localhost:8888/v1/buckets/default/collections/tasks --auth user:pass + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Last-Modified, ETag + Content-Length: 156 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 10:00:30 GMT + Etag: "1437040830468" + Last-Modified: Thu, 16 Jul 2015 10:00:30 GMT + Server: waitress + + { + "data": { + "id": "tasks", + "last_modified": 1437040830468 + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + + +Managing object permissions +=========================== + +You can use PUT or PATCH to update or replace :term:`ACLs ` for an object. + +.. note:: + + The user that run the permission update is always added to the + write ACL in order not to loose control of the object. + +A blog bucket could be created with the following to give read access to everyone. + +.. code-block:: + + $ echo '{"data":{}, "permissions": {"read": ["system.Authenticated"]}}' | \ + http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog \ + --auth user:pass + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 203 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:20:37 GMT + ETag: "1437056437581" + Last-Modified: Thu, 16 Jul 2015 14:20:37 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "servicedenuages-blog", + "last_modified": 1437056437581 + }, + "permissions": { + "read": [ + "system.Authenticated" + ], + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +Then it is possible to create ``articles`` and ``comments`` collection +with everyone having read access to their respective records. + +.. code-block:: + + $ echo '{"data":{}}' | \ + http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles \ + --auth user:pass + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 159 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:40:39 GMT + ETag: "1437057639758" + Last-Modified: Thu, 16 Jul 2015 14:40:39 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "articles", + "last_modified": 1437057639758 + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + + $ echo '{"data":{}}' | \ + http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments \ + --auth user:pass + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 159 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:41:39 GMT + ETag: "1437057699755" + Last-Modified: Thu, 16 Jul 2015 14:41:39 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "comments", + "last_modified": 1437057699755 + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +We can add an article. + +.. code-block:: + + $ echo '{"data":{"title": "My article", "content": "my content", "published_at": "Thu Jul 16 16:44:15 CEST 2015"}}' | \ + http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ + --auth user:pass + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Backoff: 10 + Connection: keep-alive + Content-Length: 278 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:43:45 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "title": "My article" + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +Everybody can read the article: + +.. code-block:: + + $ http GET https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records/b8c4cc34-f184-4b4d-8cad-e135a3f0308c \ + --auth natim: + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Last-Modified, ETag + Connection: keep-alive + Content-Length: 278 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:46:49 GMT + ETag: "1437057825171" + Last-Modified: Thu, 16 Jul 2015 14:43:45 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "title": "My article" + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +If we want everyone to be able to add a comment, we can PATCH the comments collections. + +.. code-block:: + + $ echo '{"permissions": {"record:create": ["system.Authenticated"]}}' | \ + http PATCH https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments \ + --auth user:pass + + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 200 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:49:38 GMT + ETag: "1437057699755" + Last-Modified: Thu, 16 Jul 2015 14:41:39 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "comments", + "last_modified": 1437057699755 + }, + "permissions": { + "record:create": [ + "system.Authenticated" + ], + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +Now everyone can add a comment. + +.. code-block:: + + $ echo '{"data":{"article_id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", "comment": "my comment", "author": "Natim"}}' | \ + http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments/records \ + --auth natim: + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 248 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:50:44 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "article_id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "author": "Natim", + "comment": "my comment", + "id": "5e2292d5-8818-4cd4-be7d-d5a834d36de6", + "last_modified": 1437058244384 + }, + "permissions": { + "write": [ + "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" + ] + } + } + +Permissions and groups +====================== + +It is possible to give an ACL to a group. + +Let's create a new group. + +.. code-block:: + + $ echo '{"data": {"members": ["basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc"]}}' | \ + http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/groups/writers \ + --auth user:pass + + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 247 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:54:58 GMT + ETag: "1437058498218" + Last-Modified: Thu, 16 Jul 2015 14:54:58 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "writers", + "last_modified": 1437058498218, + "members": [ + "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" + ] + }, + "permissions": { + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" + ] + } + } + +Then we can give the write ACL on the bucket for the group. + +.. code-block:: + + $ echo '{"permissions": {"write": ["/buckets/servicedenuages-blog/groups/writers"]}}' | \ + http PATCH https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog \ + --auth user:pass + + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 254 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:56:55 GMT + ETag: "1437056437581" + Last-Modified: Thu, 16 Jul 2015 14:20:37 GMT + Server: nginx/1.4.6 (Ubuntu) + + { + "data": { + "id": "servicedenuages-blog", + "last_modified": 1437056437581 + }, + "permissions": { + "read": [ + "system.Authenticated" + ], + "write": [ + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6", + "/buckets/servicedenuages-blog/groups/writers" + ] + } + } + +Now the user Natim can create articles. + +.. code-block:: + + $ echo '{"data":{"title": "Natim article", "content": "natims content", "published_at": "Thu Jul 16 16:59:16 CEST 2015"}}' | \ + http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ + --auth natim: + HTTP/1.1 201 Created + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length + Connection: keep-alive + Content-Length: 285 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 14:58:47 GMT + Server: nginx/1.4.6 (Ubuntu) + +{ + "data": { + "content": "natims content", + "id": "f9a61750-f61f-402b-8785-1647c9325a5d", + "last_modified": 1437058727907, + "published_at": "Thu Jul 16 16:59:16 CEST 2015", + "title": "Natim article" + }, + "permissions": { + "write": [ + "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" + ] + } +} + + +Listing shared items +==================== + +One can fetch the list of article. + +.. code-block:: + + $ http GET \ + https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ + --auth natim: + + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Next-Page, Total-Records, Last-Modified, ETag + Connection: keep-alive + Content-Length: 351 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 15:06:20 GMT + ETag: "1437058727907" + Last-Modified: Thu, 16 Jul 2015 14:58:47 GMT + Server: nginx/1.4.6 (Ubuntu) + Total-Records: 2 + + { + "data": [ + { + "content": "natims content", + "id": "f9a61750-f61f-402b-8785-1647c9325a5d", + "last_modified": 1437058727907, + "published_at": "Thu Jul 16 16:59:16 CEST 2015", + "title": "Natim article" + }, + { + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "title": "My article" + } + ] + } + +Or the list of comments. + + $ http GET \ + https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments/records \ + --auth natim: + + HTTP/1.1 200 OK + Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Next-Page, Total-Records, Last-Modified, ETag + Connection: keep-alive + Content-Length: 147 + Content-Type: application/json; charset=UTF-8 + Date: Thu, 16 Jul 2015 15:08:48 GMT + ETag: "1437058244384" + Last-Modified: Thu, 16 Jul 2015 14:50:44 GMT + Server: nginx/1.4.6 (Ubuntu) + Total-Records: 1 + + { + "data": [ + { + "article_id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "author": "Natim", + "comment": "my comment", + "id": "5e2292d5-8818-4cd4-be7d-d5a834d36de6", + "last_modified": 1437058244384 + } + ] + } From 9d640b82ce36a95135538f5531a6282c538d145b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20HUBSCHER?= Date: Thu, 30 Jul 2015 16:12:00 +0200 Subject: [PATCH 2/3] @leplatrem review. --- docs/api/permissions.rst | 144 +++++++++++++++++++-------------------- docs/permissions.rst | 2 + 2 files changed, 73 insertions(+), 73 deletions(-) diff --git a/docs/api/permissions.rst b/docs/api/permissions.rst index f81d4dddf..6428d6aa5 100644 --- a/docs/api/permissions.rst +++ b/docs/api/permissions.rst @@ -6,11 +6,11 @@ Permissions Before to start, make sure to have read the :ref:`Understanding permissions ` paragraph. -Permissions can be added on any manipulated objects (:ref:`buckets -`, :ref:`groups `, :ref:`collections `, +Permissions can be added on any objects (:ref:`buckets `, +:ref:`groups `, :ref:`collections `, :ref:`records `) -By default the creator of an object grab write privileges on this +By default the ``write`` permission is given to the creator of an object. @@ -19,7 +19,7 @@ How do I get my Kinto user id? To be able to add permissions for a user, the user id is needed. -The user id can be found by calling the ``/`` endpoint logged. +The currently authenticated user id can be obtained on the root url. .. code-block:: :emphasize-lines: 16 @@ -48,25 +48,19 @@ In this case the user id is: ``basicauth:631c2d625ee5726172cf67c6750de10a3e1a04b .. note:: - In case of sharing, users may need to register their user id - associated with their email address for other user to add permission - to them. + In case of sharing, users need a way to share their user id with + people that needs to give them permission. Object permissions ================== -On each object, it is possible to add ``write`` and ``read`` -permissions as well as ``sub-object:create`` ones. - .. note:: - In Kinto, object inherit their parents ones. i.e: giving the read - permission to a user on a bucket gives read permissions on all - objects stored in the bucket. - + Please make sure to have read the :ref:`permission documentation ` + first. -For instance, we can look at our own bucket permissions. +For instance, we can look at our *personal bucket* permissions. .. code-block:: @@ -82,9 +76,9 @@ For instance, we can look at our own bucket permissions. { "data": { - "id": "46524be8-0ad7-3ac6-e260-71f8993feffa", + "id": "46524be8-0ad7-3ac6-e260-71f8993feffa", "last_modified": 1437040770742 - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -93,7 +87,7 @@ For instance, we can look at our own bucket permissions. } -We can look at our own tasks collections permissions. +Similarly, the permissions of a collection can be obtained with a ``GET``: .. code-block:: @@ -109,9 +103,9 @@ We can look at our own tasks collections permissions. { "data": { - "id": "tasks", + "id": "tasks", "last_modified": 1437040830468 - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -123,14 +117,16 @@ We can look at our own tasks collections permissions. Managing object permissions =========================== -You can use PUT or PATCH to update or replace :term:`ACLs ` for an object. +Permissions can be specified during the creation of an object, and can +later be updated using PUT or PATCH. .. note:: - The user that run the permission update is always added to the - write ACL in order not to loose control of the object. + The user that updates the permissions is always given the ``write`` + permission, in order to prevent loosing ownership on the object. -A blog bucket could be created with the following to give read access to everyone. +A :ref:`blog bucket ` could be created with the following to +give read access to everyone. .. code-block:: @@ -150,26 +146,25 @@ A blog bucket could be created with the following to give read access to everyon { "data": { - "id": "servicedenuages-blog", + "id": "servicedenuages-blog", "last_modified": 1437056437581 - }, + }, "permissions": { "read": [ "system.Authenticated" - ], + ], "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" ] } } -Then it is possible to create ``articles`` and ``comments`` collection -with everyone having read access to their respective records. +Now it will be possible to create two collections (``articles`` and +``comments``) in this bucket. Users will be able to read their content. .. code-block:: - $ echo '{"data":{}}' | \ - http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles \ + $ http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles \ --auth user:pass HTTP/1.1 201 Created @@ -184,9 +179,9 @@ with everyone having read access to their respective records. { "data": { - "id": "articles", + "id": "articles", "last_modified": 1437057639758 - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -210,9 +205,9 @@ with everyone having read access to their respective records. { "data": { - "id": "comments", + "id": "comments", "last_modified": 1437057699755 - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -239,12 +234,12 @@ We can add an article. { "data": { - "content": "my content", - "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", - "last_modified": 1437057825171, - "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", "title": "My article" - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -270,12 +265,12 @@ Everybody can read the article: { "data": { - "content": "my content", - "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", - "last_modified": 1437057825171, - "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", "title": "My article" - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -283,7 +278,8 @@ Everybody can read the article: } } -If we want everyone to be able to add a comment, we can PATCH the comments collections. +If we want everyone to be able to add a comment, we can PATCH the +permissions of the ``comments`` collections. .. code-block:: @@ -303,13 +299,13 @@ If we want everyone to be able to add a comment, we can PATCH the comments colle { "data": { - "id": "comments", + "id": "comments", "last_modified": 1437057699755 - }, + }, "permissions": { "record:create": [ "system.Authenticated" - ], + ], "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" ] @@ -339,7 +335,7 @@ Now everyone can add a comment. "comment": "my comment", "id": "5e2292d5-8818-4cd4-be7d-d5a834d36de6", "last_modified": 1437058244384 - }, + }, "permissions": { "write": [ "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" @@ -352,7 +348,9 @@ Permissions and groups It is possible to give an ACL to a group. -Let's create a new group. +As described in the :ref:`use case page `, let us create a +new group ``writers``: + .. code-block:: @@ -372,12 +370,12 @@ Let's create a new group. { "data": { - "id": "writers", - "last_modified": 1437058498218, + "id": "writers", + "last_modified": 1437058498218, "members": [ "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" ] - }, + }, "permissions": { "write": [ "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6" @@ -405,15 +403,15 @@ Then we can give the write ACL on the bucket for the group. { "data": { - "id": "servicedenuages-blog", + "id": "servicedenuages-blog", "last_modified": 1437056437581 - }, + }, "permissions": { "read": [ "system.Authenticated" - ], + ], "write": [ - "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6", + "basicauth:631c2d625ee5726172cf67c6750de10a3e1a04bcd603bc9ad6d6b196fa8257a6", "/buckets/servicedenuages-blog/groups/writers" ] } @@ -436,12 +434,12 @@ Now the user Natim can create articles. { "data": { - "content": "natims content", - "id": "f9a61750-f61f-402b-8785-1647c9325a5d", - "last_modified": 1437058727907, - "published_at": "Thu Jul 16 16:59:16 CEST 2015", + "content": "natims content", + "id": "f9a61750-f61f-402b-8785-1647c9325a5d", + "last_modified": 1437058727907, + "published_at": "Thu Jul 16 16:59:16 CEST 2015", "title": "Natim article" - }, + }, "permissions": { "write": [ "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" @@ -453,7 +451,7 @@ Now the user Natim can create articles. Listing shared items ==================== -One can fetch the list of article. +One can fetch the list of articles. .. code-block:: @@ -475,17 +473,17 @@ One can fetch the list of article. { "data": [ { - "content": "natims content", - "id": "f9a61750-f61f-402b-8785-1647c9325a5d", - "last_modified": 1437058727907, - "published_at": "Thu Jul 16 16:59:16 CEST 2015", + "content": "natims content", + "id": "f9a61750-f61f-402b-8785-1647c9325a5d", + "last_modified": 1437058727907, + "published_at": "Thu Jul 16 16:59:16 CEST 2015", "title": "Natim article" - }, + }, { - "content": "my content", - "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", - "last_modified": 1437057825171, - "published_at": "Thu Jul 16 16:44:15 CEST 2015", + "content": "my content", + "id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", + "last_modified": 1437057825171, + "published_at": "Thu Jul 16 16:44:15 CEST 2015", "title": "My article" } ] diff --git a/docs/permissions.rst b/docs/permissions.rst index e2ac6c2a0..bdd264f69 100644 --- a/docs/permissions.rst +++ b/docs/permissions.rst @@ -186,6 +186,8 @@ There are two special principals: principal is useful when a rule should apply to all users. +.. _use-case: + Use-cases examples ================== From 186973693fe4ce4d2344c391bd464f65833580c9 Mon Sep 17 00:00:00 2001 From: Mathieu Leplatre Date: Fri, 14 Aug 2015 11:53:45 +0200 Subject: [PATCH 3/3] Move to tutorials section --- docs/api/index.rst | 2 - docs/index.rst | 8 +-- docs/permissions.rst | 2 +- .../first-steps.rst} | 2 +- docs/tutorials/index.rst | 10 ++++ docs/{api => tutorials}/permissions.rst | 60 ++++++++++--------- 6 files changed, 47 insertions(+), 37 deletions(-) rename docs/{tutorial.rst => tutorials/first-steps.rst} (99%) create mode 100644 docs/tutorials/index.rst rename docs/{api => tutorials}/permissions.rst (94%) diff --git a/docs/api/index.rst b/docs/api/index.rst index 869ef26d9..6690cf4d7 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -10,8 +10,6 @@ The HTTP APIs collections records groups - permissions - See `cliquet API documentation `_ for an exhaustive list of features and endpoints of the *Kinto* API. diff --git a/docs/index.rst b/docs/index.rst index 8736ed2b0..bd6124643 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,11 +18,11 @@ The server doesn't impose anything about the records data model. *Kinto* is based on top of `cliquet `_. -Tutorial -======== +Tutorials +========= Sometimes it is easier to get started by following a -tutorial. :ref:`Learn how to store, manage and sync your data `. +tutorial. :ref:`Learn how to store, sync and share your data `. Using the HTTP API ================== @@ -54,7 +54,7 @@ Table of content :maxdepth: 1 installation - tutorial + tutorials/index configuration deployment permissions diff --git a/docs/permissions.rst b/docs/permissions.rst index bdd264f69..e2dd39cec 100644 --- a/docs/permissions.rst +++ b/docs/permissions.rst @@ -186,7 +186,7 @@ There are two special principals: principal is useful when a rule should apply to all users. -.. _use-case: +.. _permissions_usecases: Use-cases examples ================== diff --git a/docs/tutorial.rst b/docs/tutorials/first-steps.rst similarity index 99% rename from docs/tutorial.rst rename to docs/tutorials/first-steps.rst index b64da1ff4..8d5a44bda 100644 --- a/docs/tutorial.rst +++ b/docs/tutorials/first-steps.rst @@ -1,4 +1,4 @@ -.. _tutorial: +.. _tutorial-first-steps: First steps with Kinto ###################### diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 000000000..02c606981 --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,10 @@ +.. _tutorials: + +Tutorials +######### + +.. toctree:: + :maxdepth: 2 + + first-steps + permissions diff --git a/docs/api/permissions.rst b/docs/tutorials/permissions.rst similarity index 94% rename from docs/api/permissions.rst rename to docs/tutorials/permissions.rst index 6428d6aa5..13404cd12 100644 --- a/docs/api/permissions.rst +++ b/docs/tutorials/permissions.rst @@ -1,4 +1,4 @@ -.. _permissions-api: +.. _tutorial-permissions: Permissions ########### @@ -21,7 +21,7 @@ To be able to add permissions for a user, the user id is needed. The currently authenticated user id can be obtained on the root url. -.. code-block:: +.. code-block:: http :emphasize-lines: 16 $ http GET http://localhost:8888/v1/ --auth user:pass @@ -62,7 +62,7 @@ Object permissions For instance, we can look at our *personal bucket* permissions. -.. code-block:: +.. code-block:: http $ http GET http://localhost:8888/v1/buckets/default --auth user:pass HTTP/1.1 200 OK @@ -89,7 +89,7 @@ For instance, we can look at our *personal bucket* permissions. Similarly, the permissions of a collection can be obtained with a ``GET``: -.. code-block:: +.. code-block:: http $ http GET http://localhost:8888/v1/buckets/default/collections/tasks --auth user:pass HTTP/1.1 200 OK @@ -125,10 +125,10 @@ later be updated using PUT or PATCH. The user that updates the permissions is always given the ``write`` permission, in order to prevent loosing ownership on the object. -A :ref:`blog bucket ` could be created with the following to +A :ref:`blog bucket ` could be created with the following to give read access to everyone. -.. code-block:: +.. code-block:: http $ echo '{"data":{}, "permissions": {"read": ["system.Authenticated"]}}' | \ http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog \ @@ -162,7 +162,7 @@ give read access to everyone. Now it will be possible to create two collections (``articles`` and ``comments``) in this bucket. Users will be able to read their content. -.. code-block:: +.. code-block:: http $ http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles \ --auth user:pass @@ -217,7 +217,7 @@ Now it will be possible to create two collections (``articles`` and We can add an article. -.. code-block:: +.. code-block:: http $ echo '{"data":{"title": "My article", "content": "my content", "published_at": "Thu Jul 16 16:44:15 CEST 2015"}}' | \ http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ @@ -249,7 +249,7 @@ We can add an article. Everybody can read the article: -.. code-block:: +.. code-block:: http $ http GET https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records/b8c4cc34-f184-4b4d-8cad-e135a3f0308c \ --auth natim: @@ -281,7 +281,7 @@ Everybody can read the article: If we want everyone to be able to add a comment, we can PATCH the permissions of the ``comments`` collections. -.. code-block:: +.. code-block:: http $ echo '{"permissions": {"record:create": ["system.Authenticated"]}}' | \ http PATCH https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments \ @@ -314,7 +314,7 @@ permissions of the ``comments`` collections. Now everyone can add a comment. -.. code-block:: +.. code-block:: http $ echo '{"data":{"article_id": "b8c4cc34-f184-4b4d-8cad-e135a3f0308c", "comment": "my comment", "author": "Natim"}}' | \ http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments/records \ @@ -348,11 +348,11 @@ Permissions and groups It is possible to give an ACL to a group. -As described in the :ref:`use case page `, let us create a +As described in the :ref:`use case page `, let us create a new group ``writers``: -.. code-block:: +.. code-block:: http $ echo '{"data": {"members": ["basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc"]}}' | \ http PUT https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/groups/writers \ @@ -385,7 +385,7 @@ new group ``writers``: Then we can give the write ACL on the bucket for the group. -.. code-block:: +.. code-block:: http $ echo '{"permissions": {"write": ["/buckets/servicedenuages-blog/groups/writers"]}}' | \ http PATCH https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog \ @@ -419,7 +419,7 @@ Then we can give the write ACL on the bucket for the group. Now the user Natim can create articles. -.. code-block:: +.. code-block:: http $ echo '{"data":{"title": "Natim article", "content": "natims content", "published_at": "Thu Jul 16 16:59:16 CEST 2015"}}' | \ http POST https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ @@ -432,20 +432,20 @@ Now the user Natim can create articles. Date: Thu, 16 Jul 2015 14:58:47 GMT Server: nginx/1.4.6 (Ubuntu) -{ - "data": { - "content": "natims content", - "id": "f9a61750-f61f-402b-8785-1647c9325a5d", - "last_modified": 1437058727907, - "published_at": "Thu Jul 16 16:59:16 CEST 2015", - "title": "Natim article" - }, - "permissions": { - "write": [ - "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" - ] + { + "data": { + "content": "natims content", + "id": "f9a61750-f61f-402b-8785-1647c9325a5d", + "last_modified": 1437058727907, + "published_at": "Thu Jul 16 16:59:16 CEST 2015", + "title": "Natim article" + }, + "permissions": { + "write": [ + "basicauth:df93ca0ecaeaa3126595f6785b39c408be2539173c991a7b2e3181a9826a69bc" + ] + } } -} Listing shared items @@ -453,7 +453,7 @@ Listing shared items One can fetch the list of articles. -.. code-block:: +.. code-block:: http $ http GET \ https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/articles/records \ @@ -491,6 +491,8 @@ One can fetch the list of articles. Or the list of comments. +.. code-block:: http + $ http GET \ https://kinto.dev.mozaws.net/v1/buckets/servicedenuages-blog/collections/comments/records \ --auth natim: