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"
        ]
    }
}

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 a 403 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. A 412 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
        }
    ]
}

Personal bucket «default»

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.org/",
    "settings": {
        "batch_max_requests": 25,
        "cliquet.batch_max_requests": 25
    },
    "user": {
        "id": "basicauth:62e79bedacd2508c7da3dfb16e9724501fb4bdf9a830de7f8abcc8f7f1496c35",
        "bucket": "b8f3fa97-3e0a-00ae-7f07-ce8ce05ce0e5",
    }
}