From c67ef01ec6942905744903df69f47764cbd44069 Mon Sep 17 00:00:00 2001 From: yuenmichelle1 Date: Wed, 27 Dec 2023 11:33:03 -0600 Subject: [PATCH] Update _collection_roles.md --- docs/source/includes/_collection_roles.md | 284 +++++++++------------- 1 file changed, 114 insertions(+), 170 deletions(-) diff --git a/docs/source/includes/_collection_roles.md b/docs/source/includes/_collection_roles.md index 6ba815169..4e4d6b5e7 100644 --- a/docs/source/includes/_collection_roles.md +++ b/docs/source/includes/_collection_roles.md @@ -1,101 +1,85 @@ -# 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 @@ -103,68 +87,12 @@ 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.