Add documentation about Buckets and permissions #36
Conversation
| Buckets | ||
| ####### | ||
|
|
||
| Buckets are a way to group users around some data. |
almet
May 5, 2015
Member
This definition doesn't say much. "Buckets are a group of collections, which can be shared accross users" seems more close to what I have in mind.
This definition doesn't say much. "Buckets are a group of collections, which can be shared accross users" seems more close to what I have in mind.
| Buckets are a way to group users around some data. | ||
|
|
||
| Basically has got an and a list of principals that can administrate | ||
| it. |
almet
May 5, 2015
Member
Sorry, what?
Sorry, what?
almet
May 5, 2015
Member
I believe we should have the same set of permissions we have for other objects (read, create, update, delete)
I believe we should have the same set of permissions we have for other objects (read, create, update, delete)
|
|
||
| { | ||
| "id": "servicedenuages", | ||
| "principals": ["email:natim@example.com"] |
almet
May 5, 2015
Member
Having "principals" returned here doesn't make a lot of sense to me, we should probably have a list of permissions and eventually a group "owners"
Having "principals" returned here doesn't make a lot of sense to me, we should probably have a list of permissions and eventually a group "owners"
Natim
May 5, 2015
Author
Member
I don't think we want fined permissions on the bucket itself, do you have a usecase in mind that needs it?
I don't think we want fined permissions on the bucket itself, do you have a usecase in mind that needs it?
| =========== | ||
|
|
||
| Creating a collection inside a bucket enable all buckets principals to | ||
| administrate the collection. |
almet
May 5, 2015
Member
I feel this should be handled by more fine grained permissions
I feel this should be handled by more fine grained permissions
| There are two kinds of data linked to a bucket: | ||
|
|
||
| - collections | ||
| - groups |
leplatrem
May 5, 2015
Contributor
I believe it makes more sense to talk about "roles" instead of "groups"
I believe it makes more sense to talk about "roles" instead of "groups"
Natim
May 5, 2015
Author
Member
Well having Daybed experience in mind I don't think it helps :) groups carries less meaning than roles. Is musicians a role?
Well having Daybed experience in mind I don't think it helps :) groups carries less meaning than roles. Is musicians a role?
almet
May 5, 2015
Member
I don't understand what a role is, but I do with a group. Why are you suggesting we could use "role"?
I don't understand what a role is, but I do with a group. Why are you suggesting we could use "role"?
Natim
May 5, 2015
Author
Member
A role is a category of people that can do specific actions (administrators, moderators, employees, managers, etc.)
A role is a category of people that can do specific actions (administrators, moderators, employees, managers, etc.)
| Collections | ||
| =========== | ||
|
|
||
| Creating a collection inside a bucket enable all buckets principals to |
leplatrem
May 5, 2015
Contributor
Principals is weird word. We probably don't want to use it.
Principals is weird word. We probably don't want to use it.
| Buckets | ||
| ####### | ||
|
|
||
| Buckets are a group of collections, shared between users, with fined |
almet
May 5, 2015
Member
fine-grained
fine-grained
| permissions on the data stored inside. | ||
|
|
||
| Basically a bucket have got an id and a list of people identifier that | ||
| can administrate it. |
almet
May 5, 2015
Member
I still believe we shouldn't go with this solution. We should have permissions associated.
I still believe we shouldn't go with this solution. We should have permissions associated.
| =========== | ||
|
|
||
| Creating a collection inside a bucket enable all buckets owners to | ||
| administrate the collection. |
almet
May 5, 2015
Member
administrate doesn't convey a lot of meaning. "To have all permissions on the collection items" seems a better description to me.
administrate doesn't convey a lot of meaning. "To have all permissions on the collection items" seems a better description to me.
Natim
May 5, 2015
Author
Member
Does: To have all permissions on all bucket collections and bucket collections items. works for you?
Does: To have all permissions on all bucket collections and bucket collections items. works for you?
almet
May 5, 2015
Member
+1
+1
| | - id | | ||
| | - data | | ||
| | - members | | ||
| +---------------+ |
almet
May 5, 2015
Member
I agree with the schema!
I agree with the schema!
| The data is not anymore linked to a specific user that only has access | ||
| to her private data but is linked to the bucket and managed by | ||
| bucket's owners (those who have the ``write_bucket`` permission on the | ||
| bucket. |
almet
May 9, 2015
Member
From this description, I cannot tell how a bucket is different from a collection. My understanding (not when reading this text) is that buckets are a container of collections, but this text kinda says it's like a collection, but open for others.
So, what's the right definition? :)
From this description, I cannot tell how a bucket is different from a collection. My understanding (not when reading this text) is that buckets are a container of collections, but this text kinda says it's like a collection, but open for others.
So, what's the right definition? :)
|
|
||
| **Optional parameters** | ||
|
|
||
| - ``permissions``: A mapping object that defines the list of user for |
almet
May 9, 2015
Member
the list of principals.
the list of principals.
|
|
||
| - ``permissions``: A mapping object that defines the list of user for | ||
| each permission | ||
| - ``write_bucket``: The list of users principals that have |
almet
May 9, 2015
Member
admins finally looks like a better option then (yes, I know).
admins finally looks like a better option then (yes, I know).
| - ``write_bucket``: The list of users principals that have | ||
| administration permissions on the bucket, the creator is | ||
| automatically added to the owner list. | ||
| - ``create_groups``: Permission to create new groups |
almet
May 9, 2015
Member
I think only admins should be allowed to do that.
I think only admins should be allowed to do that.
|
|
||
| - **read**: It means that the given user or group of users have | ||
| got read only access to the object | ||
| - **write**: It means that the given user or group of users have |
almet
May 9, 2015
Member
I would actually differenciate between create and update (which seems to be both in the "write" option here).
I would actually differenciate between create and update (which seems to be both in the "write" option here).
| attributes (schema and permissions) | ||
| - **write_collection**: It is a write access to the collection | ||
| attributes (schema and permissions) | ||
| - **create_records**: It is a permission that let one create new records |
almet
May 9, 2015
Member
oh ok it's actually here.
oh ok it's actually here.
| As soon as there is a need to let people work on the same records set | ||
| or to work with the same collection, the solution is to create a :ref:`bucket <buckets>`. | ||
|
|
||
| :ref:`Buckets <buckets>` gives a public unique name to the collection. |
leplatrem
May 11, 2015
Contributor
With the bucket name as prefix, the collection name becomes unique. (?)
With the bucket name as prefix, the collection name becomes unique. (?)
almet
May 11, 2015
Member
We're currently changing all the layout of the docs and doing another pass on this proposal. The idea is to have a default bucket for each user.
We're currently changing all the layout of the docs and doing another pass on this proposal. The idea is to have a default bucket for each user.
|
I've updated. We probably should upate the APIs as well, but I think it's wiser to wait for feedback first. |
|
|
||
| .. _buckets: | ||
|
|
||
| :ref:`Buckets <buckets>` enables the creation of collections handled by |
leplatrem
May 13, 2015
Contributor
enable
enable
| a group of ref:`User identifiers <user-identifiers>`. | ||
|
|
||
| All collections are created in a bucket. By default, it uses the connected | ||
| user's bucket (bucket only the connected user has access to). |
leplatrem
May 13, 2015
Contributor
By default, the bucket of the current user is used.
(the second part between parenthesis could not be processed by my brain at this time of the day)
By default, the bucket of the current user is used.
(the second part between parenthesis could not be processed by my brain at this time of the day)
| user's bucket (bucket only the connected user has access to). | ||
|
|
||
| :ref:`Buckets <buckets>` can be seen as namespaces: you can have different | ||
| collections using the same name, but stored in different buckets, so their |
leplatrem
May 13, 2015
Contributor
collections can have the same name across different buckets
collections can have the same name across different buckets
| collections using the same name, but stored in different buckets, so their | ||
| names don't collide. | ||
|
|
||
| Data (everything stored in a bucket: collections, groups and records) is |
leplatrem
May 13, 2015
Contributor
groups appear out of the blue here
groups appear out of the blue here
| names don't collide. | ||
|
|
||
| Data (everything stored in a bucket: collections, groups and records) is | ||
| not anymore linked to a specific user that only has access to her private data |
leplatrem
May 13, 2015
Contributor
anymore
anymore
| Data (everything stored in a bucket: collections, groups and records) is | ||
| not anymore linked to a specific user that only has access to her private data | ||
| but is linked to the bucket and managed by bucket's owners (those who have the | ||
| ``write_bucket`` permission on the bucket. |
leplatrem
May 13, 2015
Contributor
Do mention that notion of permission here. It comes after.
Do mention that notion of permission here. It comes after.
|
|
||
| - ``permissions``: A mapping object that defines the list of users for each of | ||
| the following permissions defined in the table below. In any case (even if | ||
| not specified), the current logged-in user will get access to the bucket. |
leplatrem
May 13, 2015
Contributor
The part after In any case is not clear at all. It should be put above, after the optionnally specifying....
The part after In any case is not clear at all. It should be put above, after the optionnally specifying....
| +------------------------+---------------------------------+ | ||
| | Permission | Description | | ||
| +========================+=================================+ | ||
| | ``write_bucket`` | The list of users principals | |
leplatrem
May 13, 2015
Contributor
user principals come out of the blue here
user principals come out of the blue here
| | Permission | Description | | ||
| +========================+=================================+ | ||
| | ``write_bucket`` | The list of users principals | | ||
| | | that have administration | |
leplatrem
May 13, 2015
Contributor
administration permissions come out of the blue here (it was mentioned as owner before)
administration permissions come out of the blue here (it was mentioned as owner before)
| Content-Type: application/json; charset=UTF-8 | ||
|
|
||
| { | ||
| "id": "{bucket_id}", |
leplatrem
May 13, 2015
Contributor
here those braces bring confusion. Better put some random UUID
here those braces bring confusion. Better put some random UUID
| "write_bucket": ["uid:basicauth_5d127220922673e346c0ebee46c23e6739dfa756"], | ||
| "create_groups": [], | ||
| "create_collections": [], | ||
| } |
leplatrem
May 13, 2015
Contributor
I would have prefered something like that :
"permissions": {
"admins": ["uid:basicauth_5d127220922673e346c0ebee46c23e6739dfa756"],
"groups": {
"create": []
},
"collections": {
"create": []
},
}
I would have prefered something like that :
"permissions": {
"admins": ["uid:basicauth_5d127220922673e346c0ebee46c23e6739dfa756"],
"groups": {
"create": []
},
"collections": {
"create": []
},
}
| } | ||
| } | ||
|
|
||
| There are two kinds of data linked to a bucket: **collections** and **groups**. |
leplatrem
May 13, 2015
Contributor
This is useless here, better put it above in the introduction
This is useless here, better put it above in the introduction
|
|
||
| Creating a collection inside a bucket enables all buckets users with | ||
| the ``write_bucket`` permission to have all permissions on all bucket's | ||
| collections and associated records. |
leplatrem
May 13, 2015
Contributor
Creating a collection inside a bucket enables [..] on all buckets collections ? → not clear :)
Creating a collection inside a bucket enables [..] on all buckets collections ? → not clear :)
| .. code-block:: http | ||
|
|
||
| > PUT /buckets/servicedenuages/collections/mushrooms HTTP/1.1 | ||
| < 201 Created |
leplatrem
May 13, 2015
Contributor
what is this ?
what is this ?
| "members": ["email:alexis@example.com"] | ||
| } | ||
|
|
||
| It is now possible to use the ``groups:moderators`` principal to describe |
leplatrem
May 13, 2015
Contributor
group:moderators ?
group:moderators ?
Natim
May 13, 2015
Author
Member
We've just created the group moderators the line above, I don't understand the question.
We've just created the group moderators the line above, I don't understand the question.
leplatrem
May 13, 2015
Contributor
group: singular.
group: singular.
Natim
May 13, 2015
Author
Member
Ok yes good point :)
Ok yes good point :)
| { | ||
| "id": "payments", | ||
| "acls": { |
leplatrem
May 13, 2015
Contributor
acls is not suitable IMO :)
permissions is a lot better, and consistent with buckets
acls is not suitable IMO :)
permissions is a lot better, and consistent with buckets
| "permissions": { | ||
| "read_record": ["userid:<buyer-id>", "appid:<seller-appid>"] | ||
| } | ||
| } |
leplatrem
May 13, 2015
Contributor
Same here, I would have liked this layout:
"permissions": {
"records": {
"read": ["userid:<buyer-id>", "appid:<seller-appid>"]
}
}
Same here, I would have liked this layout:
"permissions": {
"records": {
"read": ["userid:<buyer-id>", "appid:<seller-appid>"]
}
}
| } | ||
| } | ||
| Moderators are special persons with special rights. Rather than adding |
leplatrem
May 13, 2015
Contributor
rights --> permissions
rights --> permissions
| permissions on all records. | ||
| - Anybody can read everything. | ||
|
|
||
| A "microblog" bucket is created, where new groups can be created by |
leplatrem
May 13, 2015
Contributor
A twitter bucket is created
A twitter bucket is created
|
OK, I think we're good with this, should we merge? |
|
Is the close an answer to the question? |
|
Sorry for the context miss here. This branch has been merged in another temporary one which contains all work related to permissions and buckets. see #46 |
No description provided.