From 2be1defd7ac8100a7ca68d3f84f0996f8339649b Mon Sep 17 00:00:00 2001
From: David Mehren <git@herrmehren.de>
Date: Sat, 3 Oct 2020 12:46:28 +0200
Subject: [PATCH] Public API: Split-out a /notes/{note}/permissions route to
 set only permissions

Previously, the metadata route was used to both update note metadata (like title, description and tags) and the permissions. Additionally, one had to send many unchangeable properties. In this commit, a /notes/{note}/permissions route is introduced, that only changes permissions. Additionally, PUT /notes/{note}/metadata now needs only the properties that are actually changeable.

Signed-off-by: David Mehren <git@herrmehren.de>
Co-authored-by: Yannick Bungers <git@innay.de>
---
 docs/dev/public_api.yml | 116 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 102 insertions(+), 14 deletions(-)

diff --git a/docs/dev/public_api.yml b/docs/dev/public_api.yml
index fecc46375..987aceef3 100644
--- a/docs/dev/public_api.yml
+++ b/docs/dev/public_api.yml
@@ -307,17 +307,43 @@ paths:
     put:
       tags:
         - note
-      summary: Set the permissions of a note
+      summary: Set the metadata (title, description, tags) of a note
       operationId: updateNoteMetadata
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              "$ref": "#/components/schemas/NoteMetadata"
+              "$ref": "#/components/schemas/NoteMetadataUpdate"
       responses:
         '200':
-          description: The updated permissions of the note.
+          description: The updated metadata of the note.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/NoteMetadataUpdate"
+        '401':
+          "$ref": "#/components/responses/UnauthorizedError"
+        '403':
+          "$ref": "#/components/responses/ForbiddenError"
+        '404':
+          "$ref": "#/components/responses/NotFoundError"
+      parameters:
+        - name: note
+          in: path
+          required: true
+          description: The note for which the info should be shown.
+          content:
+            text/plain:
+              example: my-note
+    get:
+      tags:
+        - note
+      summary: Get the metadata of a note
+      operationId: getNoteMetadata
+      responses:
+        '200':
+          description: The metadata of the note.
           content:
             application/json:
               schema:
@@ -336,18 +362,24 @@ paths:
           content:
             text/plain:
               example: my-note
-    get:
-      tags:
-        - note
-      summary: Get the permissions of a note
-      operationId: getNoteMetadata
+  /notes/{note}/permissions:
+    put:
+      tags: [ note ]
+      summary: Set permissions of a note
+      operationId: updateNotePermissions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/NotePermissionsUpdate"
       responses:
         '200':
-          description: The permissions of the note.
+          description: The updated permissions of the note.
           content:
             application/json:
               schema:
-                "$ref": "#/components/schemas/NoteMetadata"
+                "$ref": "#/components/schemas/NotePermissionsUpdate"
         '401':
           "$ref": "#/components/responses/UnauthorizedError"
         '403':
@@ -614,6 +646,15 @@ components:
       properties:
         password:
           type: string
+    GroupInfo:
+      type: object
+      properties:
+        name:
+          type: string
+        displayName:
+          type: string
+        special:
+          type: boolean
     ImageProxyRequest:
       type: object
       properties:
@@ -681,13 +722,51 @@ components:
             type: string
         permissions:
           $ref: "#/components/schemas/NotePermissions"
+    NoteMetadataUpdate:
+      type: object
+      description: Contains only title, description and tags of a note.
+      properties:
+        title:
+          type: string
+          description: Title of the note
+        description:
+          type: string
+          description: Description of the note.
+        tags:
+          type: array
+          description: A list of tags attached to the note.
+          items:
+            type: string
     NotePermissions:
       type: object
       properties:
         owner:
-          type: string
-          description: Username of the owner of the note
-        sharedTo:
+          $ref: "#/components/schemas/UserInfo"
+        sharedToUsers:
+          type: array
+          description: Contains all users that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              user:
+                $ref: "#/components/schemas/UserInfo"
+              canEdit:
+                type: boolean
+        sharedToGroups:
+          type: array
+          description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              group:
+                $ref: "#/components/schemas/GroupInfo"
+              canEdit:
+                type: boolean
+    NotePermissionsUpdate:
+      type: object
+      description: Contains only title, description and tags of a note.
+      properties:
+        sharedToUsers:
           type: array
           description: Contains all usernames that can read the note and a boolean that denotes if they can also edit.
           items:
@@ -697,7 +776,16 @@ components:
                 type: string
               canEdit:
                 type: boolean
-
+        sharedToGroups:
+          type: array
+          description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              groupname:
+                type: string
+              canEdit:
+                type: boolean
     NoteRevisionsMetadata:
       type: array
       items: