Merge branch 'master' into user-serializer-me-attrs

zooniverse · Jan 5, 2024 · 42e4ec1 · 42e4ec1
2 parents b7e36fc + 5fd77a4
commit 42e4ec1
Show file tree

Hide file tree

Showing 20 changed files with 3,922 additions and 2 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -31,7 +31,6 @@ ADD ./Gemfile /rails_app/
 ADD ./Gemfile.lock /rails_app/
 
 RUN bundle config --global jobs `cat /proc/cpuinfo | grep processor | wc -l | xargs -I % expr % - 1`
-RUN gem update --system
 RUN bundle install --without development test
 
 ADD ./ /rails_app

diff --git a/Dockerfile.dev b/Dockerfile.dev
@@ -19,7 +19,6 @@ ADD ./Gemfile /rails_app/
 ADD ./Gemfile.lock /rails_app/
 
 RUN bundle config --global jobs `cat /proc/cpuinfo | grep processor | wc -l | xargs -I % expr % - 1`
-RUN gem update --system
 RUN bundle install
 
 ADD ./ /rails_app

diff --git a/docs/source/includes/_classifications.md b/docs/source/includes/_classifications.md
@@ -0,0 +1,222 @@
+# Classifications
+
+```json
+{
+    "classifications": [{
+        "id": 1001,
+        "created_at": "2014-08-24T22:24:32Z",
+        "updated_at": "2014-08-24T22:24:32Z",
+        "completed": false,
+        "metadata": {
+            "started_at": "2014-08-24T22:20:21Z",
+            "finished_at": "2014-08-24T22:24:31Z",
+            "user_agent": "cURL",
+            "user_language": "es_MX",
+            "workflow_version": "11.12"
+        },
+        "annotations": [
+            {
+                "task": "task-1",
+                "value": [10.4, 12.4, 13.2]
+            }
+        ],
+        "links": {
+            "user": "1",
+            "subjects": ["10"],
+            "workflow": "81",
+            "project": "2"
+        }
+    }],
+    "links": {
+        "classifications.user": {
+            "href": "/users/{classifications.user}",
+            "type": "classifications"
+        },
+        "classifications.project": {
+            "href": "/projects/{classifications.project}",
+            "type": "projects"
+        },
+        "classifications.workflow": {
+            "href": "/workflows/{classification.workflow}",
+            "type": "workflows"
+        },
+        "classifications.subject": {
+            "href": "/subjects/{classifications.subjects}",
+            "type": "subjects"
+        }
+    },
+}
+
+```
+
+A single Classification resource object. This represents a _user's_
+responses to a _workflow's_ questions about a _subject_.
+
+A classification has the following attributes:
+
+Attribute | Type | Description
+--------- | ---- | -----------
+id | integer | read-only
+created_at | string | read-only
+updated_at | string | read-only
+completed | string | read-only
+metadata | hash |
+gold_standard | boolean |
+annotations | array(hash) |
+
+Annotations is an array of maps of the form `{ "task": "task_key",
+"value": "question answer" }`. Metadata contains additional information about a
+classification including:
+
+- started_at
+- finished_at
+- user_agent
+- workflow_version
+- user_language
+
+
+## List classifications
+
+```http
+GET /api/classifications HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+```
+
+Only lists classifications the active user has made or projects the user has edit permissions for.
+
+Classifications have special collection routes that indicate the scope you would like to retrieve.
+
+Possible options are:
+
++ `/api/classifications/` default, will fetch the current user's past complete classifications.
++ `/api/classifications/incomplete` will fetch the current user's past incomplete classifications.
++ `/api/classifications/project` will fetch classifications from projects a user has 'edit' permissions for
++ `/api/classifications/gold_standard` will fetch gold standard classifications for all marked workflows
+
+Any of the scopes may be further filtered using the *project_id*, *workflow_id*
+and *user_group_id* parameters.
+
+### Parameters
+
++ page (optional, integer) ... index of the collection page, 1 is default
++ page_size (optional, integer) ... number of items on a page. 20 is default
++ sort (optional, string) ... fields to sort collection by. updated_at is default
++ project_id (optional, integer) ... only retrieve classifications for a specific project
++ workflow_id (optional, integer) ... only retrieve classifications for a specific workflow
++ user_group_id (optional, integer) ... only retrieve classifications for a specific user group
++ include (optional, string) ... comma separated list of linked resources to return with the collection
++ last_id (optional, integer) ... only classifications with ids greater than `last_id` will be returned (`/project` only, requires project_id)
+
+<aside class="notice">
+Please note that due to the cost of the page count queries on the
+classifications table we are not returning the page counts for
+this end point, please use the previous and next hrefs to page into the data.
+</aside>
+
+
+## Retrieve a single Classification
+
+```http
+GET /api/classifications/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+```
+
+A User may retrieve any classification, irrespective of the complete status.
+
+### Parameters
+
++ `id` (required, integer) ... integer id of the resource to retrieve
+
+
+
+## Create a Classification [POST]
+
+```http
+POST /api/classifications HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+
+{
+    "classifications": {
+        "completed": false,
+        "metadata": {
+            "started_at": "2014-08-24T22:20:21Z",
+            "finished_at": "2014-08-24T22:24:31Z",
+            "user_agent": "cURL",
+            "user_language": "es_MX",
+            "workflow_version": "11.12"
+        },
+        "annotations": [
+            {
+              "task": "task-name",
+              "value": "Any type: string, hash, array, etc"
+            }
+        ],
+        "links": {
+            "subjects": ["11"],
+            "workflow": "81",
+            "project": "2"
+        }
+    }
+}
+```
+
+Create a classification by providing a JSON-API formatted object, that
+must include _metadata_, _annotations_ and a _links_ hash. Optionally, it
+may include the _completed_ field, which if not included defaults to true.
+The completed field is used to store half-completed classifications, so the user
+can later continue from where they stopped.
+
+The _links_ hash must contain a _subjects_ hash, a _project_ and a _workflow_.
+The _metadata_ hash must contain all the keys specified in the example.
+Please note, the _workflow_version_ should be the value returned from the
+specific workflow representation. The annotations array must be in the
+format specified in the example, i.e. an array of objects, containing a _task_ and a _value_.
+The _task_ can be anything and must not necessarily align with the tasks of the workflow
+(even though that is generally not advised).
+
+
+
+
+## Edit a single Classification [PUT]
+
+```http
+PUT /api/classifications/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+
+{
+    "classifications": {
+        "annotations": [
+            {
+                "task": "task-1",
+                "value": [10.4, 12.4, 13.2]
+            },
+            {
+                "task": "workflow-2",
+                "value": "fishy"
+            }
+        ],
+        "completed": true
+    }
+}
+```
+
+A User may modify an incomplete classification. It should be marked as
+completed when done.
+
+The *annotations* attributes must be returned as a full representation
+of the annotations array.
+
+
+## Destroy a single Classification [DELETE]
+
+```http
+DELETE /api/classifications/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+```
+
+A User may delete an incomplete classification.
diff --git a/docs/source/includes/_collection_preferences.md b/docs/source/includes/_collection_preferences.md
@@ -0,0 +1,104 @@
+# Collection preferences
+
+```json
+{
+    "collection_preferences": [{
+        "id": "942",
+        "preferences": {
+            "display": "grid"
+        },
+        "created_at": "2014-03-20T06:23:12Z",
+        "updated_at": "2014-04-21T08:22:22Z",
+        "links": {
+            "user" : "30",
+            "collection": "11"
+        }
+    }],
+    "links": {
+        "collection_preferences.user": {
+            "href": "/user/{collection_preferences.user}",
+            "type": "users"
+        },
+        "collection_preferences.collection": {
+            "href": "/collections/{collection_preferences.collection}",
+            "type": "collections"
+        }
+    }
+}
+```
+
+A Collection Preference resource captures a user's settings for a
+particular collection.
+
+It has the following attributes:
+
+- id
+- created_at
+- updated_at
+- preferences
+
+*id*, *created_at*, and *updated_at* are set the by the API. Collection
+ preferences are only visible to user they belong to.
+
+## List collection preferences
+
+All collections add a meta attribute hash containing paging information.
+
+### 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
++ sort (optional, string) ... field to sort by
++ user_id (optional, integer) ... user_id to see preferences for
++ collection_id (optional, integer) ... collection_id to see preferences for
++ include (optional, string) ... comma separated list of linked resources to load
+
+
+## Retrieve a single CollectionPreference [GET]
+
+### Parameters
+
++ include (optional, string) ... comma separated list of linked resources to load
+
+
+## Edit a CollectionPreference [PUT]
+
+```http
+PUT /api/collection_preferences/123 HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+
+{
+    "collection_preferences": {
+        "preferences": {
+            "receive_updates": false,
+        }
+    }
+}
+```
+
+Only the owning user may edit a Collection Preference resource. The preferences field may be edited. Editing the preferences field requires a full representation of the preferences object to be sent.
+
+## Create a CollectionPreference [POST]
+
+```http
+POST /api/collection_preferences HTTP/1.1
+Accept: application/vnd.api+json; version=1
+Content-Type: application/json
+
+{
+    "collection_preferences": {
+        "preferences": {
+            "display": "grid"
+        },
+        "links": {
+            "collection": "1"
+        }
+    }
+}
+```
+
+Creating a Collection Preference requires only a link to a collection. Optionally an object of settings for preferences may be included.
+
+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.
+