Update _collection_roles.md

zooniverse · Dec 27, 2023 · c67ef01 · c67ef01
1 parent ea74797
commit c67ef01
Showing 1 changed file with 114 additions and 170 deletions.
diff --git a/docs/source/includes/_collection_roles.md b/docs/source/includes/_collection_roles.md
@@ -1,170 +1,98 @@
-# Group CollectionRole
-Resources related to Roles for _Panoptes Collections_
+# CollectionRole
+```json
+{
+    "links": {
+        "collection_roles.owner": {
+            "href": "/{collection_roles.owner.href}",
+            "type": "owners"
+        },
+        "collection_roles.collection": {
+            "href": "/collections/{collection_roles.collection}",
+            "type": "collections"
+        }
+    },
+    "meta": {
+        "collection_roles": {
+            "page": 1,
+            "page_size": 2,
+            "count": 28,
+            "include": [],
+            "page_count": 14,
+            "previous_page": 14,
+            "next_page": 2,
+            "first_href": "/collection_roles?page_size=2",
+            "previous_href": "/collection_roles?page=14page_size=2",
+            "next_href": "/collection_roles?page=2&page_size=2",
+            "last_href": "/collection_roles?page=14&page_size=2"
+        }
+    },
+    "collection_roles": [{
+        "id": "942",
+        "roles": ["collaborator"],
+        "created_at": "2014-03-20T06:23:12Z",
+        "updated_at": "2014-04-21T08:22:22Z",
+        "links": {
+            "collection": "11",
+            "owner": {
+                "id": "4",
+                "display_name": "Owner 4",
+                "type": "user_groups",
+                "href": "user_groups/4"
+            }
+        }
+    },{
+    "id": "949",
+        "roles": ["viewer"],
+        "created_at": "2014-08-20T06:23:12Z",
+        "updated_at": "2014-09-21T08:22:22Z",
+        "links": {
+            "collection": "81",
+            "owner": {
+                "id": "1",
+                "display_name": "Owner 1",
+                "type": "users",
+                "href": "users/1"
+            }
+        }
+    }]
+}
+```
 
-## CollectionRole [/collection_roles/{id}{?include}]
+Resources related to Roles for _Panoptes Collections_
 A Collection Role resources contains an array of roles assigned to a user
 for a particular collection.
 
 It has the following attributes:
 
-- id
-- created_at
-- updated_at
-- roles
+Attribute | Type | Description
+--------- | ---- | -----------
+id | integer | read-only
+created_at | string | read-only
+updated_at | string | read-only
+roles | array(string) |
 
 *id*, *created_at*, and *updated_at* are set the by the API. Collection
 roles are visible to the collection owner and the user given roles.
 
-Collection roles may be:
+### Collection Role Types
 - `collaborator` - full access to edit or delete a collection
 - `viewer` - may view a private collection
 
-+ Parameters
-  + id (required, integer) ... integer identifier of the collection role resource
-
-+ Model
-
-    + Body
-
-            {
-                "links": {
-                    "collection_roles.owner": {
-                        "href": "/{collection_roles.owner.href}",
-                        "type": "owners"
-                    },
-                    "collection_roles.collection": {
-                        "href": "/collections/{collection_roles.collection}",
-                        "type": "collections"
-                    }
-                },
-                "collection_roles": [{
-                    "id": "942",
-                    "roles": ["collaborator"],
-                    "created_at": "2014-03-20T06:23:12Z",
-                    "updated_at": "2014-04-21T08:22:22Z",
-                    "links": {
-                        "collection": "11",
-                        "owner": {
-                            "id": "4",
-                            "display_name": "Owner 4",
-                            "type": "user_groups",
-                            "href"=>"user_groups/4"
-                        }
-                    }
-                }]
-            }
-
-### Retrieve a single CollectionRole [GET]
-+ Parameters
-  + include (optional, string) ... comma separate list of linked resources to load
-
-+ Request
-
-    + Headers
-
-            Accept: application/vnd.api+json; version=1
-            Content-Type: application/json
-
-+ Response 200
-
-    [CollectionRole][]
-
-### Edit a CollectionRole [PUT]
-A user with permissions to edit a collection may modify roles for other
-users in the collection. A user without edit permissions may not edit
-their own roles.
-
-Editing requires sending a full representation of the roles array.
+## List All Collection Roles
 
-+ Request
-
-    + Headers
-
-            Accept: application/vnd.api+json; version=1
-            Content-Type: application/json
-
-    + Body
-
-            {
-                "collection_roles": {
-                    "roles": ["viewer"]
-                }
-            }
-
-+ Response 200
-
-    [CollectionRole][]
-
-## CollectionRole Collection [/collection_roles{?user_id,collection_id,page,page_size,sort,include}]
 A Collection of CollectionRole resources.
 
 All collections add a meta attribute hash containing paging
 information.
 
 CollectionRoles are returned as an array under *collection_roles*.
 
-+ Model
-
-    + Body
-
-            {
-                "links": {
-                    "collection_roles.owner": {
-                        "href": "/{collection_roles.owner.href}",
-                        "type": "owners"
-                    },
-                    "collection_roles.collection": {
-                        "href": "/collections/{collection_roles.collection}",
-                        "type": "collections"
-                    }
-                },
-                "meta": {
-                    "collection_roles": {
-                        "page": 1,
-                        "page_size": 2,
-                        "count": 28,
-                        "include": [],
-                        "page_count": 14,
-                        "previous_page": 14,
-                        "next_page": 2,
-                        "first_href": "/collection_roles?page_size=2",
-                        "previous_href": "/collection_roles?page=14page_size=2",
-                        "next_href": "/collection_roles?page=2&page_size=2",
-                        "last_href": "/collection_roles?page=14&page_size=2"
-                    }
-                },
-                "collection_roles": [{
-                    "id": "942",
-                    "roles": ["collaborator"],
-                    "created_at": "2014-03-20T06:23:12Z",
-                    "updated_at": "2014-04-21T08:22:22Z",
-                    "links": {
-                        "collection": "11",
-                        "owner": {
-                            "id": "4",
-                            "display_name": "Owner 4",
-                            "type": "user_groups",
-                            "href"=>"user_groups/4"
-                        }
-                    }
-                },{
-                "id": "949",
-                    "roles": ["viewer"],
-                    "created_at": "2014-08-20T06:23:12Z",
-                    "updated_at": "2014-09-21T08:22:22Z",
-                    "links": {
-                        "collection": "81",
-                        "owner": {
-                            "id": "1",
-                            "display_name": "Owner 1",
-                            "type": "users",
-                            "href"=>"users/1"
-                        }
-                    }
-                }]
-            }
+```http
+GET /api/collection_roles HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+```
 
-### List all CollectionRoles [GET]
 + Parameters
   + page (optional, integer) ... the index of the page to retrieve default is 1
   + page_size (optional, integer) ... number of items to include on a page default is 20
@@ -173,40 +101,56 @@ CollectionRoles are returned as an array under *collection_roles*.
   + collection_id (optional, integer) ... collection_id to see roles for
   + include (optional, string) ... comma separate list of linked resources to load
 
-+ Request
 
-    + Headers
 
-            Accept: application/vnd.api+json; version=1
-            Content-Type: application/json
+## Retrieve a single CollectionRole
 
-+ Response 200
+```http
+GET /api/collection_roles/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+```
 
-    [CollectionRole Collection][]
++ Parameters
+  + id (required, integer) ... integer identifier of the collection role resource
+  + include (optional, string) ... comma separate list of linked resources to load
 
-### Create a CollectionRole [POST]
-Creating a Collection Role resource requires a link to a user and a
-collection. You may also include an array of roles.
+## Create a CollectionRole
+```http
 
-+ Request
+POST /api/collection_roles/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
 
-    + Headers
+{
+    "collection_roles": {
+        "roles": ["collaborator"],
+        "links": {
+            "collection": "1",
+            "user": "842"
+        }
+    }
+}
+```
 
-            Accept: application/vnd.api+json; version=1
-            Content-Type: application/json
+Creating a Collection Role resource requires a link to a user and a
+collection. You may also include an array of roles.
 
-    + Body
 
-            {
-                "collection_roles": {
-                    "roles": ["collaborator"],
-                    "links": {
-                        "collection": "1",
-                        "user": "842"
-                    }
-                }
-            }
+## Edit a CollectionRole
+```http
+PUT /api/collection_roles/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
 
-+ Response 201
+{
+    "collection_roles": {
+        "roles": ["viewer"]
+    }
+}
+```
+A user with permissions to edit a collection may modify roles for other
+users in the collection. A user without edit permissions may not edit
+their own roles.
 
-    [CollectionRole][]
+Editing requires sending a full representation of the roles array.