Merge pull request #1259 from brontolosone/user-preferences-api-docs

API docs for user preferences
getodk · Dec 3, 2024 · 0bc6209 · 0bc6209
2 parents 54817a3 + 593a378
commit 0bc6209
Showing 1 changed file with 208 additions and 2 deletions.
diff --git a/docs/api.yaml b/docs/api.yaml
@@ -592,7 +592,6 @@ tags:
     * The **Metadata Document** defines the data schema using [an XML-based standard](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_Introduction). It is linked in every OData response.
 
     * The **data documents**, linked from the Service Document, are a simple JSON representation of the Submission or Entity data, conforming to the schema we describe in our Metadata Document.
-
 - name: System Endpoints
   description: There are some resources available for getting or setting system information
     and configuration. You can set the [Usage Reporting configuration](/central-api-system-endpoints/#usage-reporting-configuration)
@@ -646,6 +645,12 @@ tags:
   x-parent-tag: Accounts and Users
   description: |-
     Presently, it is possible to create and list `User`s in the system, as well as to perform password reset operations. In future versions of this API it will be possible to manage existing user information and delete accounts as well.
+- name: User Preferences
+  x-parent-tag: Accounts and Users
+  description: |-
+    The Central frontend uses this API to save various user preferences, such as the sorting order of certain listings. When a user starts a new session, these preferences are loaded in as part of the [User object](/central-api-accounts-and-users/#getting-authenticated-user-details).
+
+    Preferences can be set site-wide or per-project.
 - name: App Users
   x-parent-tag: Accounts and Users
   description: |-
@@ -1473,17 +1478,204 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error403'
       x-codegen-request-body-name: body
+  /v1/user-preferences/project/{projectId}/{propertyName}:
+    put:
+      tags:
+        - User Preferences
+      summary: Setting a project preference
+      parameters:
+        - name: projectId
+          in: path
+          description: The integer ID of the `Project`.
+          required: true
+          schema:
+            type: integer
+          example: 42
+        - name: propertyName
+          in: path
+          description: The name of the preference.
+          required: true
+          schema:
+            type: string
+          example: "frobwazzleEnabled"
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              required:
+              - propertyValue
+              type: any
+              properties:
+                propertyValue:
+                  type: any
+                  description: The preference to be stored. It may be of any json-serializable type.
+              example:
+                propertyValue: true
+        required: true
+      responses:
+        200:
+          description: The preference was stored
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+        403:
+          description: Forbidden - supplied bearer token was not valid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error403'
+        404:
+          description: The specified project does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error404'
+    delete:
+      tags:
+        - User Preferences
+      summary: Deleting a project preference
+      parameters:
+        - name: projectId
+          in: path
+          description: The integer ID of the `Project`.
+          required: true
+          schema:
+            type: integer
+          example: 42
+        - name: propertyName
+          in: path
+          description: The name of the preference.
+          required: true
+          schema:
+            type: string
+          example: "frobwazzleEnabled"
+        - name: Authorization
+          in: header
+          description: Bearer encoding of a token of the user whose preferences to operate on
+          required: true
+          schema:
+            type: string
+          example: Bearer lSpAIeksRu1CNZs7!qjAot2T17dPzkrw9B4iTtpj7OoIJBmXvnHM8z8Ka4QPEjR7
+      responses:
+        200:
+          description: The preference was stored
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+        403:
+          description: Forbidden - supplied bearer token was not valid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error403'
+        404:
+          description: The preference does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error404'
+  /v1/user-preferences/site/{propertyName}:
+    put:
+      tags:
+        - User Preferences
+      summary: Setting a sitewide preference
+      parameters:
+        - name: propertyName
+          in: path
+          description: The name of the preference.
+          required: true
+          schema:
+            type: string
+          example: "frobwazzleEnabled"
+        - name: Authorization
+          in: header
+          description: Bearer encoding of a token of the user whose preferences to operate on
+          required: true
+          schema:
+            type: string
+          example: Bearer lSpAIeksRu1CNZs7!qjAot2T17dPzkrw9B4iTtpj7OoIJBmXvnHM8z8Ka4QPEjR7
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              required:
+              - propertyValue
+              type: any
+              properties:
+                propertyValue:
+                  type: any
+                  description: The preference to be stored. It may be of any json-serializable type.
+              example:
+                propertyValue: true
+        required: true
+
+      responses:
+        200:
+          description: The preference was stored
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+        403:
+          description: Forbidden - supplied bearer token was not valid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error403'
+    delete:
+      tags:
+        - User Preferences
+      summary: Deleting a sitewide preference
+      parameters:
+        - name: propertyName
+          in: path
+          description: The name of the preference.
+          required: true
+          schema:
+            type: string
+          example: "frobwazzleEnabled"
+        - name: Authorization
+          in: header
+          description: Bearer encoding of a token of the user whose preferences to operate on
+          required: true
+          schema:
+            type: string
+          example: Bearer lSpAIeksRu1CNZs7!qjAot2T17dPzkrw9B4iTtpj7OoIJBmXvnHM8z8Ka4QPEjR7
+      responses:
+        200:
+          description: The preference was deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+        403:
+          description: Forbidden - supplied bearer token was not valid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error403'
+          404:
+          description: The specified preference does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error404'
   /v1/users/current:
     get:
       tags:
       - Users
+      - User Preferences
       summary: Getting authenticated User details
       description: |-
         Typically, you would get User details by the User's numeric Actor ID.
 
         However, if you only have a Bearer token, for example, you don't have any information about the user attached to that session, including even the ID with which to get more information. So you can instead supply the text `current` to get the user information associated with the authenticated session.
 
-        If you _do_ use `current`, you may request extended metadata. Supply an `X-Extended-Metadata` header value of `true` to additionally retrieve an array of strings of the `verbs` the authenticated User/Actor is allowed to perform server-wide.
+        If you _do_ use `current`, you may request extended metadata. Supply an `X-Extended-Metadata` header value of `true` to additionally receive:
+        - an array of strings of the `verbs` the authenticated User/Actor is allowed to perform server-wide
+        - an object containing the preferences of the authenticated User/Actor
       operationId: Getting authenticated User details
       responses:
         200:
@@ -1573,6 +1765,14 @@ paths:
                       server-wide.
                     items:
                       type: object
+                  preferences:
+                    description: The preferences of this user
+                    type: object
+                    properties:
+                      site:
+                        type: object
+                      projects:
+                        type: object
               example:
                 createdAt: 2018-04-18T23:19:14.802Z
                 displayName: My Display Name
@@ -1584,6 +1784,12 @@ paths:
                 verbs:
                 - project.create
                 - project.update
+                preferences:
+                  site:
+                    projectSortMode: latest
+                  projects:
+                    "1":
+                      formTrashCollapsed: false
         403:
           description: Forbidden
           content: