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="bob:" --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="bob:"
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="bob:" --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="bob:" --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="bob:" --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
        }
    ]
}