Add documentation about Buckets and permissions

docs/api/buckets.rst

@@ -0,0 +1,170 @@
+Working with buckets
+====================
+
+.. _buckets:
+
+
+Creating a new bucket
+---------------------
+
+``/buckets/<bucket_id>``
+
+This endpoint defines the bucket resource:
+
+* Its permissions
+
+
+POST /buckets
+'''''''''''''
+
+**Requires authentication**
+
+This endpoint creates a new bucket with a generated unique id.
+
+By default the user id is used for its write permission.
+
+.. code-block:: http
+
+    $ http POST http://localhost:8000/v1/buckets --auth "admin:"
+    POST /v1/buckets HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    HTTP/1.1 201 Created
+
+    {
+        "id": "857d952b-e9fa-4b9f-b60e-cb633a557ced",
+        "permissions": {
+            "write": ["basicauth:5d127220922673e346c0ebee46c23e6739dfa756"]
+        }
+    }
+
+
+PUT /buckets/<bucket_id>
+''''''''''''''''''''''''
+
+**Requires authentication**
+
+This endpoint creates a new bucket with a chosen id.
+
+If the bucket exists and you don't have the ``write`` permission on
+it, you will get a ``403 Forbidden`` http response.
+
+.. code-block:: http
+
+    $ http PUT http://localhost:8000/v1/buckets/servicedenuages --auth "admin:"
+
+    PUT /v1/buckets/servicedenuages HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    HTTP/1.1 201 Created
+
+    {
+        "id": "servicedenuages",
+        "permissions": {
+            "write": ["basicauth:5d127220922673e346c0ebee46c23e6739dfa756"]
+        }
+    }
+
+
+Updating a bucket
+-----------------
+
+PATCH /buckets/<bucket_id>
+''''''''''''''''''''''''''
+
+**Requires authentication**
+
+This endpoint lets you update an existing bucket.
+
+If you are not owner of the bucket you will get a ``403 Forbidden`` http response.
+
+The PATCH endpoint let you add or remove users principals from
+permissions sets. In case you want to override the set, you can use
+the PUT endpoint.
+
+You can use ``+principal`` to add one and ``-principal`` to remove one.
+
+.. code-block:: http
+
+    $ echo '{
+              "permissions": {
+                "write": ["+fxa:af3e077eb9f5444a949ad65aa86e82ff"],
+                "groups:create": ["+fxa:70a9335eecfe440fa445ba752a750f3d"]
+              }
+            }' | http PATCH http://localhost:8000/v1/buckets/servicedenuages --auth "admin:"
+
+    PATCH /v1/buckets/servicedenuages HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    {
+        "permissions": {
+            "write_bucket": [
+                "+fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ], 
+            "create_groups": [
+                "+fxa:70a9335eecfe440fa445ba752a750f3d"
+            ]
+        }
+    }
+
+    HTTP/1.1 200 OK
+    Content-Type: application/json; charset=UTF-8
+
+    {
+        "id": "servicedenuages",
+        "permissions": {
+            "write": [
+                "basicauth:5d127220922673e346c0ebee46c23e6739dfa756",
+                "fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ],
+            "groups:create": [
+                "fxa:70a9335eecfe440fa445ba752a750f3d"
+            ]
+        }
+    }
+
+
+Getting bucket information
+--------------------------
+
+GET /buckets/<bucket_id>
+''''''''''''''''''''''''
+
+This endpoint lets you get bucket information.
+
+.. code-block:: http
+
+    $ http GET http://localhost:8000/v1/buckets/servicedenuages
+
+    GET /v1/buckets/servicedenuages HTTP/1.1
+
+    HTTP/1.1 200 OK
+    Content-Type: application/json; charset=UTF-8
+
+    {
+        "id": "servicedenuages",
+        "permissions": {
+            "write": [
+                "basicauth:5d127220922673e346c0ebee46c23e6739dfa756",
+                "fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ],
+            "groups:create": [
+                "fxa:70a9335eecfe440fa445ba752a750f3d"
+            ]
+        }
+    }
+
+
+Removing a bucket
+-----------------
+
+This endpoint lets you delete a bucket and everything inside.
+
+.. code-block:: http
+
+    $ http DELETE http://localhost:8000/v1/buckets/servicedenuages
+
+    DELETE /v1/buckets/servicedenuages HTTP/1.1
+
+    HTTP/1.1 204 No Content
+    Content-Type: application/json; charset=UTF-8

docs/api/collections.rst

@@ -0,0 +1,52 @@
+Working with collections
+========================
+
+.. _collections:
+
+Collections are always linked to a `bucket <buckets>`_.
+
+
+.. note:: 
+
+    By default users have a bucket that is used for their own data.
+
+    Application can use this default bucket with the ``~`` shortcut.
+
+	ie: ``/buckets/~/collections/contacts`` will be the current user contacts.
+
+
+/buckets/<bucket_id>/collections/<collection_id>
+================================================
+
+**Requires authentication**
+
+End-point for the collection of records:
+
+* Create record
+* Fetch, sort and filter records
+
+.. note::
+
+    A collection is considered empty by default. In other words, no error will
+    be thrown if the collection id is unknown.
+
+See `cliquet resource documentation
+<http://cliquet.readthedocs.org/en/latest/api/resource.html#get-resource>`_
+for more details on available operations.
+
+
+/buckets/<bucket_id>/collections/<collection_id>/records/<record_id>
+====================================================================
+
+**Requires authentication**
+
+End-point for a single record of the collection:
+
+* Fetch
+* Modify
+* Replace
+* Delete
+
+
+See `cliquet record documentation <http://cliquet.readthedocs.org/en/latest/api/resource.html#get-resource-id>`_
+for more details on available operations.

docs/api/groups.rst

@@ -0,0 +1,164 @@
+Working with groups
+===================
+
+.. _groups:
+
+
+Creating a new group
+---------------------
+
+``/buckets/<bucket_id>/groups/<group_id>``
+
+This endpoint defines the group resource:
+
+* Its permissions
+* Its members
+
+
+POST /buckets/<bucket_id>/groups
+''''''''''''''''''''''''''''''''
+
+**Requires authentication**
+
+This endpoint creates a new bucket's group with a generated unique id.
+
+.. code-block:: http
+
+    $ echo '{
+              "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f"]
+            }' | http POST http://localhost:8000/v1/buckets/cloudservices_blog/groups --auth "admin:"
+    POST /v1/buckets/cloudservices_blog/groups HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    HTTP/1.1 201 Created
+
+    {
+        "id": "5d875b92-ef9a-49bf-6b0e-bc6353a5c7ed",
+        "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f"]
+    }
+
+
+PUT /buckets/<bucket_id>/groups/<group_id>
+''''''''''''''''''''''''''''''''''''''''''
+
+**Requires authentication**
+
+This endpoint creates a new group with a chosen id.
+
+.. code-block:: http
+
+    $ echo '{
+              "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f"]
+            }' | http PUT http://localhost:8000/v1/buckets/cloudservices_blog/groups/moderators \
+          --auth "admin:"
+
+    {
+        "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f"]
+    }
+
+    PUT /v1/buckets/cloudservices_blog/groups/moderators HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    HTTP/1.1 201 Created
+
+    {
+        "id": "moderators",
+        "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f"]
+    }
+
+
+Updating a group
+----------------
+
+PATCH /buckets/<bucket_id>/groups/<group_id>
+''''''''''''''''''''''''''''''''''''''''''''
+
+**Requires authentication**
+
+This endpoint lets you update an existing bucket.
+
+The PATCH endpoint let you add or remove users principals from
+permissions and member sets. 
+
+In case you want to override the set, you can use the PUT endpoint.
+
+You can use ``+principal`` to add one and ``-principal`` to remove one.
+
+.. code-block:: http
+
+    $ echo '{
+              "members": ["+fxa:70a9335eecfe440fa445ba752a750f3d"]
+              "permissions": {
+                "write": ["+fxa:af3e077eb9f5444a949ad65aa86e82ff"]
+              }
+            }' | http PATCH http://localhost:8000/v1/buckets/cloudservices_blog/groups/moderators --auth "admin:"
+
+    PATCH /v1/buckets/cloudservices_blog/groups/moderators HTTP/1.1
+    Authorization: Basic YWRtaW46
+
+    {
+        "members": [
+            "+fxa:70a9335eecfe440fa445ba752a750f3d"
+        ],
+        "permissions": {
+            "write": [
+                "+fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ]
+        }
+    }
+
+    HTTP/1.1 200 OK
+    Content-Type: application/json; charset=UTF-8
+
+    {
+        "id": "moderators",
+        "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f", "fxa:70a9335eecfe440fa445ba752a750f3d"]
+        "permissions": {
+            "write": [
+                "fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ]
+        }
+    }
+
+
+Getting group information
+-------------------------
+
+GET /buckets/<bucket_id>/groups/<group_id>
+''''''''''''''''''''''''''''''''''''''''''
+
+This endpoint lets you get groups information.
+
+.. code-block:: http
+
+    $ http GET http://localhost:8000/v1/buckets/cloudservices_blog/groups/moderators
+
+    GET /v1/buckets/cloudservices_blog/groups/moderators HTTP/1.1
+
+    HTTP/1.1 200 OK
+    Content-Type: application/json; charset=UTF-8
+
+    {
+        "id": "moderators",
+        "members": ["fxa:fae307e97bf5494a4a46d95aa86e2f8f", "fxa:70a9335eecfe440fa445ba752a750f3d"]
+        "permissions": {
+            "write": [
+                "fxa:af3e077eb9f5444a949ad65aa86e82ff"
+            ]
+        }
+    }
+
+
+Removing a group
+----------------
+
+This endpoint lets you delete a group.
+
+.. code-block:: http
+
+    $ http DELETE http://localhost:8000/v1/buckets/cloudservices_blog/groups/moderators
+
+    DELETE /v1/buckets/cloudservices_blog/groups/moderators HTTP/1.1
+
+    HTTP/1.1 204 No Content
+    Content-Type: application/json; charset=UTF-8