Groups¶
A group associates a name to a list of principals. It is useful in order to handle permissions. Groups are defined in buckets.
A group is a mapping with the following attributes:
members
: a list of principalspermissions
: (optional) the ACLs for the group object (e.g who is allowed to read or update the group itself.)
Creating a group¶
-
POST
/buckets/
(bucket_id)/groups
¶ Synopsis: Creates a new bucket group with a generated ID. Requires authentication
Example Request
$ echo '{"data": {"members": ["basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6"]}}' | http POST http://localhost:8888/v1/buckets/blog/groups --auth="token:bob-token" --verbose
POST /v1/buckets/blog/groups HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 102 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Example Response
HTTP/1.1 201 Created Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 248 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 16:17:02 GMT Server: waitress { "data": { "id": "wZjuQfpS", "last_modified": 1434644222033, "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Replacing a group¶
-
PUT
/buckets/
(bucket_id)/groups/
(group_id)¶ Synopsis: Creates or replaces a group with a chosen ID. Requires authentication
Example Request
$ echo '{"data": {"members": ["basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6"]}}' | http put http://localhost:8888/v1/buckets/blog/groups/readers --auth="token:bob-token" --verbose
PUT /v1/buckets/blog/groups/readers HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 102 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Example Response
HTTP/1.1 201 Created Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 247 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 16:41:01 GMT Server: waitress { "data": { "id": "readers", "last_modified": 1434645661227, "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Note
In order to create only if 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.
Retrieving a group¶
-
GET
/buckets/
(bucket_id)/groups/
(group_id)¶ Synopsis: Returns the group object. Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets/blog/groups/readers --auth="token:bob-token" --verbose
GET /v1/buckets/blog/groups/readers HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive 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: 247 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 16:44:07 GMT Etag: "1434645847532" Last-Modified: Thu, 18 Jun 2015 16:44:07 GMT Server: waitress { "data": { "id": "readers", "last_modified": 1434645661227, "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Retrieving all groups¶
-
GET
/buckets/
(bucket_id)/groups
¶ Synopsis: Returns the list of groups for the bucket. Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets/blog/groups --auth="token:bob-token" --verbose
GET /v1/buckets/blog/groups HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive 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, Next-Page, Total-Records, Last-Modified, ETag Content-Length: 147 Content-Type: application/json; charset=UTF-8 Date: Thu, 13 Aug 2015 12:16:05 GMT Etag: "1439468156451" Last-Modified: Thu, 13 Aug 2015 12:15:56 GMT Server: waitress Total-Records: 1 { "data": [ { "id": "vAQSwSca", "last_modified": 1439468156451, "members": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } ] }
Deleting a group¶
-
DELETE
/buckets/
(bucket_id)/groups/
(group_id)¶ Synopsis: Deletes a specific group. Requires authentication
Example Request
$ http delete http://localhost:8888/v1/buckets/blog/groups/readers --auth="token:bob-token" --verbose
DELETE /v1/buckets/blog/groups/readers 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: 70 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 16:47:29 GMT Server: waitress { "data": { "deleted": true, "id": "readers", "last_modified": 1434646049488 } }