Buckets¶
A bucket is the parent object of collections and groups.
A bucket is a mapping with the following attributes:
permissions
: (optional) the ACLs for the bucket object
Creating a bucket¶
-
POST
/buckets
¶ Synopsis: Creates a new bucket. If id
is not provided, it is automatically generated.Requires authentication
Example Request
$ echo '{"data": {"id": "blog"}}' | http POST http://localhost:8888/v1/buckets --auth="token:bob-token" --verbose
POST /v1/buckets HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 25 Content-Type: application/json; charset=utf-8 Host: localhost:8888 User-Agent: HTTPie/0.8.0 { "data": { "id": "blog" } }
Example Response
HTTP/1.1 201 Created Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length Content-Length: 155 Content-Type: application/json; charset=UTF-8 Date: Thu, 10 Sep 2015 08:34:32 GMT Server: waitress { "data": { "id": "blog", "last_modified": 1441874072429 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
A bucket also accept arbitrary attributes. For example, you may want to store some application settings there.
Replacing a bucket¶
-
PUT
/buckets/
(bucket_id)¶ Synopsis: Creates or replaces a bucket with a specific ID. Requires authentication
If the bucket exists but you don’t have the
write
permission, you will get a403 Forbidden
http response.Example request
$ http put http://localhost:8888/v1/buckets/blog --auth="token:bob-token"
PUT /v1/buckets/blog HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 0 Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 155 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 15:19:10 GMT Server: waitress { "data": { "id": "blog", "last_modified": 1434640750988 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Note
In order to create only if it does not exist yet, a
If-None-Match: *
request header can be provided. A412 Precondition Failed
error response will be returned if the record already exists.
Retrieve an existing bucket¶
-
GET
/buckets/
(bucket_id)¶ Synopsis: Returns a specific bucket by its ID. Requires authentication
Example request
$ http get http://localhost:8888/v1/buckets/blog --auth="token:bob-token" --verbose
GET /v1/buckets/blog HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 13 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag Content-Length: 155 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 15:25:19 GMT Etag: "1434641119102" Last-Modified: Thu, 18 Jun 2015 15:25:19 GMT Server: waitress { "data": { "id": "blog", "last_modified": 1434640750988 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Updating an existing bucket¶
-
PATCH
/buckets/
(bucket_id)¶ Synopsis: Modifies an existing bucket. Requires authentication
Note
Until a formalism is found to alter ACL principals (e.g. using
+
or-
) there is no difference in the behaviour between PATCH and PUT.
Deleting a bucket¶
-
DELETE
/buckets/
(bucket_id)¶ Synopsis: Deletes a specific bucket and everything under it. Requires authentication
Example request
$ http delete http://localhost:8888/v1/buckets/blog --auth="token:bob-token" --verbose
DELETE /v1/buckets/blog HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 0 Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 67 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 15:29:42 GMT Server: waitress { "data": { "deleted": true, "id": "blog", "last_modified": 1434641382954 } }
Retrieving all buckets¶
-
GET
/buckets
¶ Synopsis: Returns the list of accessible buckets Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets --auth="token:bob-token" --verbose
GET /v1/buckets HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Host: localhost:8888 User-Agent: HTTPie/0.8.0
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Next-Page, Total-Records, Last-Modified, ETag Content-Length: 54 Content-Type: application/json; charset=UTF-8 Date: Thu, 10 Sep 2015 08:37:32 GMT Etag: "1441874072429" Last-Modified: Thu, 10 Sep 2015 08:34:32 GMT Server: waitress Total-Records: 1 { "data": [ { "id": "blog", "last_modified": 1441874072429 } ] }
Delete all buckets¶
-
DELETE
/buckets
¶ Synopsis: Delete every writable buckets for this user Requires authentication
Example Request
$ http delete http://localhost:8888/v1/buckets --auth="token:bob-token" --verbose
DELETE /v1/buckets HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic YWxpY2U6 Connection: keep-alive Content-Length: 0 Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Retry-After, Content-Length, Alert, Backoff Content-Length: 101 Content-Type: application/json; charset=UTF-8 Date: Fri, 26 Feb 2016 14:12:22 GMT Server: waitress { "data": [ { "deleted": true, "id": "e64db3f9-6a60-1acf-fc3a-7d1ba7e823aa", "last_modified": 1456495942515 } ] }
Personal bucket «default»¶
When the built-in plugin kinto.plugins.default_bucket
is enabled in configuration, a bucket default
is available.
As explained in the section about collections, the default
bucket implicitly creates the collections objects on their first use.
-
GET
/buckets/default
¶ Synopsis: Returns the current user personnal bucket. Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets/default -v --auth='token:bob-token'
GET /v1/buckets/default HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Host: localhost:8888 User-Agent: HTTPie/0.8.0
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Content-Length, Expires, Alert, Retry-After, Last-Modified, ETag, Pragma, Cache-Control, Backoff Content-Length: 187 Content-Type: application/json; charset=UTF-8 Date: Wed, 28 Oct 2015 16:29:00 GMT Etag: "1446049740955" Last-Modified: Wed, 28 Oct 2015 16:29:00 GMT Server: waitress { "data": { "id": "b8f3fa97-3e0a-00ae-7f07-ce8ce05ce0e5", "last_modified": 1446049740955 }, "permissions": { "write": [ "basicauth:62e79bedacd2508c7da3dfb16e9724501fb4bdf9a830de7f8abcc8f7f1496c35" ] } }
For convenience, the actual default bucket id is provided in the root URL of Kinto:
-
GET
/
¶ Synopsis: Obtain current user personnal bucket in root URL. Requires authentication
Example Request
$ http get http://localhost:8888/v1/ -v --follow --auth='token:bob-token'
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Retry-After, Content-Length, Alert, Backoff Content-Length: 400 Content-Type: application/json; charset=UTF-8 Date: Wed, 28 Oct 2015 16:52:49 GMT Server: waitress { "hello": "kinto", "version": "1.7.0.dev0" "url": "http://localhost:8888/v1/", "documentation": "https://kinto.readthedocs.io/", "settings": { "batch_max_requests": 25, }, "user": { "id": "basicauth:62e79bedacd2508c7da3dfb16e9724501fb4bdf9a830de7f8abcc8f7f1496c35", "bucket": "b8f3fa97-3e0a-00ae-7f07-ce8ce05ce0e5", } }