updated acl docs

HDFGroup · Nov 10, 2015 · f6c3224 · f6c3224
1 parent 6c5d31c
commit f6c3224
Show file tree

Hide file tree

Showing 4 changed files with 345 additions and 2 deletions.
diff --git a/docs/AclOps/GET_ACL.rst b/docs/AclOps/GET_ACL.rst
@@ -38,7 +38,8 @@ To get a user's access information for a committed datatype:
 where:
 
 *<id>* is the UUID of the requested dataset/group/committed datatype.
-*<userid>* is the userid for the requested user
+*<userid>* is the userid for the requested user.  Use the special userid "default" to 
+get the default access permisions for the object.
 
 Request Parameters
 ------------------
@@ -133,7 +134,7 @@ Sample Response
     },
     "hrefs": [
         {
-            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acl/test_user1",
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1",
             "rel": "self"
         },
         {

diff --git a/docs/AclOps/GET_ACLs.rst b/docs/AclOps/GET_ACLs.rst
@@ -0,0 +1,183 @@
+**********************************************
+GET ACLs
+**********************************************
+
+Description
+===========
+Returns access information for all users defined in the ACL (Access Control List) 
+for the object with the UUID provided in the URI.
+
+Requests
+========
+
+Syntax
+------
+
+To get the ACL for a group:
+
+.. code-block:: http
+    GET /groups/<id>/acls HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+    
+
+To get the ACL for a dataset:
+
+.. code-block:: http
+    GET /datasets/<id>/acls HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+    
+
+To get the ACL for a committed datatype:
+
+.. code-block:: http
+    GET /datatypes/<id>/acls HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+
+where:
+
+*<id>* is the UUID of the requested dataset/group/committed datatype.
+
+Request Parameters
+------------------
+This implementation of the operation does not use request parameters.
+
+Request Headers
+---------------
+This implementation of the operation uses only the request headers that are common
+to most requests.  See :doc:`../CommonRequestHeaders`
+
+Responses
+=========
+
+Response Headers
+----------------
+
+This implementation of the operation uses only response headers that are common to 
+most responses.  See :doc:`../CommonResponseHeaders`.
+
+Response Elements
+-----------------
+
+On success, a JSON response will be returned with the following elements:
+
+
+acls
+^^^^
+A JSON list that contains one element for each user specified in the ACL.
+The elements will be JSON object that describe the users acces permisions.  
+Subkeys of the element are are:
+
+userName: the userid of the user ('default' for the default access)
+
+create: A boolean flag that indicated if the user is authorized to create new resources
+
+delete: A boolean flag that indicated if the user is authorized to delete resources
+
+read: A boolean flag that indicated if the user is authorized to read (GET) resources
+
+update: A boolean flag that indicated if the user is authorized to update resources
+
+readACL: A boolean flag that indicated if the user is authorized to read the object's ACL
+
+updateACL: A boolean flag that indicated if the user is authorized to update the object's ACL
+
+
+hrefs
+^^^^^
+An array of hypertext links to related resources.  See :doc:`../Hypermedia`.
+
+Special Errors
+--------------
+
+The implementation of the operation does not return special errors.  For general 
+information on standard error codes, see :doc:`../CommonErrorResponses`.
+
+Examples
+========
+
+Sample Request
+--------------
+
+.. code-block:: http
+
+    GET /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls  HTTP/1.1
+    host: tall.test.hdfgroup.org
+    Accept-Encoding: gzip, deflate
+    Accept: */*
+    User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
+    
+Sample Response
+---------------
+
+.. code-block:: http
+
+    HTTP/1.1 200 OK
+    Date: Fri, 16 Jan 2015 20:06:08 GMT
+    Content-Length: 660
+    Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1"
+    Content-Type: application/json
+    Server: TornadoServer/3.2.2
+    
+.. code-block:: json
+
+    {
+    "acls": [
+        {
+            "create": true,
+            "delete": true,
+            "read": true,
+            "readACL": true,
+            "update": true,
+            "updateACL": true,
+            "userName": "test_user2"
+        },
+        {
+            "create": false,
+            "delete": false,
+            "read": true,
+            "readACL": false,
+            "update": false,
+            "updateACL": false,
+            "userName": "test_user1"
+        },
+        {
+            "create": false,
+            "delete": false,
+            "read": false,
+            "readACL": false,
+            "update": false,
+            "updateACL": false,
+            "userName": "default"
+        }
+    ],
+    "hrefs": [
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls",
+            "rel": "self"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e",
+            "rel": "root"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/",
+            "rel": "home"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e",
+            "rel": "owner"
+        }
+    ]
+    
+Related Resources
+=================
+
+* :doc:`PUT_ACL`
+* :doc:`GET_ACL`
+
+ 
+
+ 
diff --git a/docs/AclOps/PUT_ACL.rst b/docs/AclOps/PUT_ACL.rst
@@ -0,0 +1,157 @@
+**********************************************
+PUT ACL
+**********************************************
+
+Description
+===========
+Update the access information for the given user for the object with the UUID provided in the URI.
+
+Requests
+========
+
+Syntax
+------
+
+To update a user's access information for a group:
+
+.. code-block:: http
+    PUT /groups/<id>/acls/<userid> HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+    
+
+To get a user's access information for a dataset:
+
+.. code-block:: http
+    PUT /datasets/<id>/acls/<userid> HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+    
+
+To get a user's access information for a committed datatype:
+
+.. code-block:: http
+    PUT /datatypes/<id>/acls/<userid> HTTP/1.1
+    Host: DOMAIN
+    Authorization: <authorization_string>
+
+where:
+
+*<id>* is the UUID of the requested dataset/group/committed datatype.
+*<userid>* is the userid for the requested user.  Use the special userid "default" to 
+get the default access permisions for the object.
+
+Request Parameters
+------------------
+This implementation of the operation does not use request parameters.
+
+Request Headers
+---------------
+This implementation of the operation uses only the request headers that are common
+to most requests.  See :doc:`../CommonRequestHeaders`
+
+Request Elements
+----------------
+
+The request body most include a JSON object that has the following keys and boolean values:
+
+ { 
+ 'read': <True or False>, 
+
+ 'create': <True or False>, 
+
+ 'update': <True or False>, 
+
+ 'delete': <True or False>, 
+
+ 'readACL': <True or False>, 
+
+ 'updateACL': <True or False> 
+
+ }
+
+Responses
+=========
+
+Response Headers
+----------------
+
+This implementation of the operation uses only response headers that are common to 
+most responses.  See :doc:`../CommonResponseHeaders`.
+
+Response Elements
+-----------------
+
+On success, a JSON response will be returned with the following elements:
+
+
+hrefs
+^^^^^
+An array of hypertext links to related resources.  See :doc:`../Hypermedia`.
+
+Special Errors
+--------------
+
+The implementation of the operation does not return special errors.  For general 
+information on standard error codes, see :doc:`../CommonErrorResponses`.
+
+Examples
+========
+
+Sample Request
+--------------
+
+.. code-block:: http
+
+    PUT /groups/052dcbbd-9d33-11e4-86ce-3c15c2da029e/acls/test_user1 HTTP/1.1
+    host: tall.test.hdfgroup.org
+    Accept-Encoding: gzip, deflate
+    Accept: */*
+    User-Agent: python-requests/2.3.0 CPython/2.7.8 Darwin/14.0.0
+    
+    { 'read': True, 'create': False, 'update': False, 
+             'delete': False, 'readACL': False, 'updateACL': False }
+    
+Sample Response
+---------------
+
+.. code-block:: http
+
+    HTTP/1.1 201 Created
+    Date: Fri, 16 Jan 2015 20:06:08 GMT
+    Content-Length: 660
+    Etag: "2c410d1c469786f25ed0075571a8e7a3f313cec1"
+    Content-Type: application/json
+    Server: TornadoServer/3.2.2
+    
+.. code-block:: json
+
+    
+    "hrefs": [
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e/acls/test_user1",
+            "rel": "self"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e",
+            "rel": "root"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/",
+            "rel": "home"
+        },
+        {
+            "href": "http://tall_acl.test.hdfgroup.org/groups/eb8f6959-8775-11e5-96b6-3c15c2da029e",
+            "rel": "owner"
+        }
+    ]
+    
+Related Resources
+=================
+
+* :doc:`GET_ACL`
+* :doc:`GET_ACLs`
+
+
+
+
diff --git a/docs/AclOps/index.rst b/docs/AclOps/index.rst
@@ -93,5 +93,7 @@ List of Operations
    :maxdepth: 1
 
    GET_ACL
+   GET_ACLs
+   PUT_ACL