Update _project_preferences.md

zooniverse · Dec 28, 2023 · fbcf3b9 · fbcf3b9
1 parent 3edeab4
commit fbcf3b9
Showing 1 changed file with 130 additions and 199 deletions.
diff --git 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][]