-
Notifications
You must be signed in to change notification settings - Fork 419
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #46 from mozilla-services/bucket-permissions-api
Bucket permissions api
- Loading branch information
Showing
6 changed files
with
783 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.