From fbcf3b94da3440d621e95dc7e4cd3dca2b616e59 Mon Sep 17 00:00:00 2001 From: yuenmichelle1 Date: Wed, 27 Dec 2023 19:08:15 -0600 Subject: [PATCH] Update _project_preferences.md --- docs/source/includes/_project_preferences.md | 329 ++++++++----------- 1 file changed, 130 insertions(+), 199 deletions(-) diff --git a/docs/source/includes/_project_preferences.md b/docs/source/includes/_project_preferences.md index c207e6c9a..4947dd8db 100644 --- a/docs/source/includes/_project_preferences.md +++ b/docs/source/includes/_project_preferences.md @@ -1,161 +1,82 @@ -# Group ProjectPreference -Resources related to setting preferences for _Panoptes Projects_ +# Project Preferences +```json + { + "links": { + "project_preferences.user": { + "href": "/user/{project_preferences.user}", + "type": "users" + }, + "project_preferences.project": { + "href": "/projects/{project_preferences.project}", + "type": "projects" + } + }, + "meta": { + "project_preferences": { + "page": 1, + "page_size": 2, + "count": 28, + "include": [], + "page_count": 14, + "previous_page": 14, + "next_page": 2, + "first_href": "/project_preferences?page_size=2", + "previous_href": "/project_preferences?page=14page_size=2", + "next_href": "/project_preferences?page=2&page_size=2", + "last_href": "/project_preferences?page=14&page_size=2" + } + }, + "project_preferences": [{ + "id": "942", + "email_communication": true, + "preferences": { + "tutorial": true + }, + "created_at": "2014-03-20T06:23:12Z", + "updated_at": "2014-04-21T08:22:22Z", + "links": { + "user" : "30", + "project": "11" + } + },{ + "id": "949", + "email_communication": true, + "preferences": { + "tutorial": true + }, + "created_at": "2014-08-20T06:23:12Z", + "updated_at": "2014-09-21T08:22:22Z", + "links": { + "user" : "33", + "project": "81" + } + }] +} +``` -## ProjectPreference [/project_preferences/{id}{?include}] A Project Preference resource captures a user's settings for a particular project. It has the following attributes: -- id -- created_at -- updated_at -- preferences -- email_communication +Attribute | Type | Description +--------- | ---- | ----------- +id | integer | read-only +created_at | datetime | read-only +updated_at | datetime | read-only +preferences | jsonb | +email_communication | boolean | *id*, *created_at*, and *updated_at* are set the by the API. Project preferences are only visible to user they belong to. -+ Parameters - + id (required, integer) ... integer identifier of resource - -+ Model - - + Body - - { - "links": { - "project_preferences.user": { - "href": "/user/{project_preferences.user}", - "type": "users" - }, - "project_preferences.project": { - "href": "/projects/{project_preferences.project}", - "type": "projects" - } - }, - "project_preferences": [{ - "id": "942", - "email_communication": true, - "preferences": { - "tutorial": true - }, - "created_at": "2014-03-20T06:23:12Z", - "updated_at": "2014-04-21T08:22:22Z", - "links": { - "user" : "30", - "project": "11" - } - }] - } - -### Retrieve a single ProjectPreference [GET] -+ Parameters - + include (optional, string) ... comma separated list of linked resources to load - -+ Request - - + Headers - - Accept: application/vnd.api+json; version=1 - Content-Type: application/json - -+ Response 200 - - [ProjectPreference][] - -### Edit a ProjectPreference [PUT] -Only the owning user may edit a Project Preference resource. The -email_communication field and the preferences field may be edited. - -Editing the preferences field requires a full representation of the -preferences hash to be sent. - -+ Request - - + Headers - - Accept: application/vnd.api+json; version=1 - Content-Type: application/json - - + Body - - { - "project_preferences": { - "preferences": { - "mini_course": false, - } - } - } - -+ Response 200 - - [ProjectPreference][] - -## ProjectPreference Collection [/project_preferences{?user_id,project_id,page,page_size,sort,include}] -A Collection of ProjectPreference resources. -All collections add a meta attribute hash containing paging -information. - -ProjectPreferences are returned as an array under *project_preferences*. - -+ Model - - { - "links": { - "project_preferences.user": { - "href": "/user/{project_preferences.user}", - "type": "users" - }, - "project_preferences.project": { - "href": "/projects/{project_preferences.project}", - "type": "projects" - } - }, - "meta": { - "project_preferences": { - "page": 1, - "page_size": 2, - "count": 28, - "include": [], - "page_count": 14, - "previous_page": 14, - "next_page": 2, - "first_href": "/project_preferences?page_size=2", - "previous_href": "/project_preferences?page=14page_size=2", - "next_href": "/project_preferences?page=2&page_size=2", - "last_href": "/project_preferences?page=14&page_size=2" - } - }, - "project_preferences": [{ - "id": "942", - "email_communication": true, - "preferences": { - "tutorial": true - }, - "created_at": "2014-03-20T06:23:12Z", - "updated_at": "2014-04-21T08:22:22Z", - "links": { - "user" : "30", - "project": "11" - } - },{ - "id": "949", - "email_communication": true, - "preferences": { - "tutorial": true - }, - "created_at": "2014-08-20T06:23:12Z", - "updated_at": "2014-09-21T08:22:22Z", - "links": { - "user" : "33", - "project": "81" - } - }] - } - -### List all ProjectPreferences [GET] +## List all ProjectPreferences +```http +GET /project_preferences HTTP/1.1 +Accept: application/vnd.api+json; version=1 +Content-Type: application/json +``` + 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 @@ -164,18 +85,39 @@ ProjectPreferences are returned as an array under *project_preferences*. + project_id (optional, integer) ... project_id to see preferences for + include (optional, string) ... comma separated list of linked resources to load -+ Request +Responses will have meta attribute hash containing paging information. - + Headers - - Accept: application/vnd.api+json; version=1 - Content-Type: application/json - -+ Response 200 +ProjectPreferences are returned as an array under *project_preferences*. - [ProjectPreference Collection][] -### Create a ProjectPreference [POST] +## Retrieve a single ProjectPreference +```http +GET /api/project_preferences/123 HTTP/1.1 +Accept: application/vnd.api+json; version=1 +Content-Type: application/json +``` ++ Parameters + + id (required, integer) ... integer identifier of resource + + include (optional, string) ... comma separated list of linked resources to load + +## Create a ProjectPreference +```http +POST /api/project_preferences HTTP/1.1 +Accept: application/vnd.api+json; version=1 +Content-Type: application/json + +{ + "project_preferences": { + "email_communication": true, + "preferences": { + "tutorial": true + }, + "links": { + "project": "1" + } + } +} +``` Creating a Project Preference requires only a link to a project. Optionally a boolean flag for email_communication or a hash of settings for preferences may be included. @@ -184,32 +126,41 @@ Since a user can only create, read, or modify their own preferences the currently logged in user is always set as the linked user on creation. -+ Request - - + Headers - - Accept: application/vnd.api+json; version=1 - Content-Type: application/json - - + Body - - { - "project_preferences": { - "email_communication": true, - "preferences": { - "tutorial": true - }, - "links": { - "project": "1" - } - } - } +## Edit a ProjectPreference +```http +PUT /api/project_preferences/123 HTTP/1.1 +Accept: application/vnd.api+json; version=1 +Content-Type: application/json + +{ + "project_preferences": { + "preferences": { + "mini_course": false, + } + } +} +``` +Only the owning user may edit a Project Preference resource. The +email_communication field and the preferences field may be edited. -+ Response 201 +Editing the preferences field requires a full representation of the +preferences hash to be sent. - [ProjectPreference][] -### Edit a ProjectPreference Setting [POST] +## Edit ProjectPreferences Settings +```http +POST /api/project_preferencess?user_id=1&project_id=1 HTTP/1.1 +Accept: application/vnd.api+json; version=1 +Content-Type: application/json + +{ + "project_preferences": { + "settings": { + "workflow_id": 1234, + } + } +} +``` Project owners may edit the settings attribute of any user's Project Preferences associated with that project (and only that project). You need to provide the "user_id" and the "project_id" to specify the resource to apply the settings update to. Note: in the settings payload the @@ -218,23 +169,3 @@ to specify the resource to apply the settings update to. Note: in the settings p + Parameters + user_id (string) ... The id of the user whose preference needs updating + project_id (string) ... The id of the project the preference setting should be scoped to -+ Request - - + Headers - - Accept: application/vnd.api+json; version=1 - Content-Type: application/json - - + Body - - { - "project_preferences": { - "settings": { - "workflow_id": 1234, - } - } - } - -+ Response 200 - - [ProjectPreference][]