Skip to content

Commit

Permalink
Merge pull request #51 from mozilla-services/documentation-improvements
Browse files Browse the repository at this point in the history 
Documentation improvements
  • Loading branch information
@Natim
Natim committed Jun 16, 2015
2 parents 0a31a1a + 1e83275 commit 77d2161
Show file tree
Hide file tree
Showing 8 changed files with 687 additions and 624 deletions.
345 changes: 345 additions & 0 deletions docs/access-control-lists.rst
View file

Large diffs are not rendered by default.

205 changes: 98 additions & 107 deletions docs/api/buckets.rst
View file
Original file line number Diff line number Diff line change
@@ -1,117 +1,71 @@
Working with buckets
====================

.. _buckets:

Buckets
#######

Creating a new bucket
---------------------

``/buckets/<bucket_id>``

This endpoint defines the bucket resource:
The bucket is the parent object of collections and groups.

* Its permissions
A bucket is a mapping with the following attributes:


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"]
}
}
* ``permissions``: (*optional*) the :term:`ACLs <ACL>` for the bucket object


PUT /buckets/<bucket_id>
''''''''''''''''''''''''
========================

**Requires authentication**

This endpoint creates a new bucket with a chosen id.
Creates or replaces a bucket with a specific 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
$ http PUT http://localhost:8888/v1/buckets/blog --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 43
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 12:54:53 GMT
Server: waitress
{
"id": "servicedenuages",
"id": "blog",
"last_modified": 1433940893322,
"permissions": {
"write": ["basicauth:5d127220922673e346c0ebee46c23e6739dfa756"]
}
}
.. note::

Updating a bucket
-----------------

PATCH /buckets/<bucket_id>
''''''''''''''''''''''''''

**Requires authentication**
In order to create only if does not exist yet, a ``If-None-Match: *``
request header can be provided. A ``412 Precondition Failed`` error response
will be returned if the record already exists.

This endpoint lets you update an existing bucket.

If you are not owner of the bucket you will get a ``403 Forbidden`` http response.
GET /buckets/<bucket_id>
========================

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.
**Requires authentication**

You can use ``+principal`` to add one and ``-principal`` to remove one.
Returns a specific bucket by its id.

.. 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 GET http://localhost:8888/v1/buckets/blog --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Content-Length: 43
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 13:03:26 GMT
Last-Modified: 1433941406398
Server: waitress
{
"id": "servicedenuages",
"id": "blog",
"last_modified": 1433940893322,
"permissions": {
"write": [
"basicauth:5d127220922673e346c0ebee46c23e6739dfa756",
Expand All @@ -124,47 +78,84 @@ You can use ``+principal`` to add one and ``-principal`` to remove one.
}
Getting bucket information
--------------------------
PATCH /buckets/<bucket_id>
==========================

GET /buckets/<bucket_id>
''''''''''''''''''''''''
**Requires authentication**

This endpoint lets you get bucket information.
Modifies an existing bucket.

.. code-block:: http
.. note::

$ http GET http://localhost:8000/v1/buckets/servicedenuages
Until a formalism is found to alter ACL principals (e.g. using ``+`` or ``-``)
there is no difference in the behaviour between PATCH and PUT.

GET /v1/buckets/servicedenuages HTTP/1.1
.. 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.
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
.. You can use ``+principal`` to add one and ``-principal`` to remove one.
{
"id": "servicedenuages",
"permissions": {
"write": [
"basicauth:5d127220922673e346c0ebee46c23e6739dfa756",
"fxa:af3e077eb9f5444a949ad65aa86e82ff"
],
"groups:create": [
"fxa:70a9335eecfe440fa445ba752a750f3d"
]
}
}
.. .. code-block:: http
.. $ echo '{
.. "permissions": {
.. "write": ["+fxa:af3e077eb9f5444a949ad65aa86e82ff"],
.. "groups:create": ["+fxa:70a9335eecfe440fa445ba752a750f3d"]
.. }
.. }' | http PATCH http://localhost:8000/v1/buckets/servicedenuages --auth "admin:"
Removing a bucket
-----------------
.. 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"
.. ]
.. }
.. }
This endpoint lets you delete a bucket and everything inside.
.. code-block:: http
$ http DELETE http://localhost:8000/v1/buckets/servicedenuages
DELETE /buckets/<bucket_id>
===========================

DELETE /v1/buckets/servicedenuages HTTP/1.1
**Requires authentication**

Deletes a specific bucket, and **everything under it**.

.. code-block:: http
HTTP/1.1 204 No Content
$ http DELETE http://localhost:8888/v1/buckets/blog --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 58
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 13:07:17 GMT
Server: waitress
{
"deleted": true,
"id": "blog",
"last_modified": 1433941637723
}
106 changes: 79 additions & 27 deletions docs/api/collections.rst
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,104 @@
Working with collections
========================

.. _collections:

Collections are always linked to a `bucket <buckets>`_.
Collections
###########

A collection belongs to a bucket and stores records.

A collection is a mapping with the following attributes:

.. note::
* ``permissions``: (*optional*) the :term:`ACLs <ACL>` for the collection object

By default users have a bucket that is used for their own data.

Application can use this default bucket with the ``~`` shortcut.
.. .. note::

ie: ``/buckets/~/collections/contacts`` will be the current user contacts.
.. 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>
================================================
PUT /buckets/<bucket_id>/collections/<collection_id>
====================================================

**Requires authentication**

End-point for the collection of records:
Creates or replaces a collection object.

.. code-block:: http
* Create record
* Fetch, sort and filter records
$ http PUT http://localhost:8888/v1/buckets/blog/collections/articles --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 47
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 13:10:30 GMT
Server: waitress
{
"id": "articles",
"last_modified": 1433941830569,
"permissions": {
"write": [
"fxa:af3e077eb9f5444a949ad65aa86e82ff"
]
}
}
.. note::

A collection is considered empty by default. In other words, no error will
be thrown if the collection id is unknown.
In order to create only if does not exist yet, a ``If-None-Match: *``
request header can be provided. A ``412 Precondition Failed`` error response
will be returned if the record already exists.


GET /buckets/<bucket_id>/collections/<collection_id>
====================================================

**Requires authentication**

Returns the collection object.

.. code-block:: http
$ http GET http://localhost:8888/v1/buckets/blog/collections/articles --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Content-Length: 47
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 13:11:25 GMT
Last-Modified: 1433941885974
Server: waitress
See `cliquet resource documentation
<http://cliquet.readthedocs.org/en/latest/api/resource.html#get-resource>`_
for more details on available operations.
{
"id": "articles",
"last_modified": 1433941830569,
"permissions": {
"write": [
"fxa:af3e077eb9f5444a949ad65aa86e82ff"
]
}
}
/buckets/<bucket_id>/collections/<collection_id>/records/<record_id>
====================================================================
DELETE /buckets/<bucket_id>/collections/<collection_id>
=======================================================

**Requires authentication**

End-point for a single record of the collection:
Deletes a specific collection, and **everything under it**.

* Fetch
* Modify
* Replace
* Delete
.. code-block:: http
$ http DELETE http://localhost:8888/v1/buckets/blog/collections/articles --auth "admin:"
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 62
Content-Type: application/json; charset=UTF-8
Date: Wed, 10 Jun 2015 13:13:55 GMT
Server: waitress
See `cliquet record documentation <http://cliquet.readthedocs.org/en/latest/api/resource.html#get-resource-id>`_
for more details on available operations.
{
"deleted": true,
"id": "articles",
"last_modified": 1433942035743
}

0 comments on commit 77d2161

Please sign in to comment.