Merge pull request #136 from ZeitOnline/ZO-4493

feat: add 'merkl' bookmarks, categories and 'content' teaser endpoints

Refs: ZO-4493

docs/api/api.yaml

@@ -23,6 +23,170 @@ servers:
           - "0.3.1"
 
 paths:
+  /teaser/{uuid}:
+    get:
+      security:
+          - cookieAuthProduction: []
+          - cookieAuthStaging: []
+      description: Returns a single teaser element
+      parameters:
+        - in: path
+          name: uuid
+          required: true
+          schema:
+            $ref: "#/components/schemas/UUID"
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/CenterpageTeaser"
+                  - $ref: "#/components/schemas/CenterpageTeaserVideo"
+                  - $ref: "#/components/schemas/CenterpageTeaserPodcast"
+                  - $ref: "#/components/schemas/CenterpageTeaserAudio"
+          description: "Success"
+        "400":
+          description: "Something was wrong. Check the body for error messages."
+        "401":
+          description: "Unauthorized to get teaser"
+        "404":
+          description: "Not found"
+        "503":
+          description: "Service unavailable"
+
+  /merkl/bookmarks:
+    get:
+      security:
+        - cookieAuthProduction: []
+        - cookieAuthStaging: []
+      description:
+        Returns list of bookmarks, optionally filtered by category.<br>
+        Calling this endpoint without parameters returns all bookmarks.<br>
+        To get only bookmarks by a given category, call this endpoint with the `category` parameter.
+      parameters:
+        - in: query
+          name: category
+          required: false
+          schema:
+            type: string
+            description: Category
+            example: "podcast"
+          description: category to filter list of bookmarks
+          example: "?category=podcast"
+      tags:
+        - bookmarks
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                anyOf:
+                  - $ref: "#/components/schemas/Bookmark"
+                  - $ref: "#/components/schemas/Category"
+          description: "Success"
+        "400":
+          description: "Something was wrong with the request to get bookmarks. Check the body for error messages."
+        "401":
+          description: "Unauthorized to get bookmarks"
+        "503":
+          description: "Service unavailable to get bookmarks"
+    post:
+      security:
+        - cookieAuthProduction: []
+        - cookieAuthStaging: []
+      operationId: postBookmark
+      description: Add a new bookmark
+      tags:
+        - bookmarks
+      requestBody:
+        description: Adds the given UUID at bookmarklist
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                uuid:
+                  $ref: "#/components/schemas/UUID"
+      responses:
+        "201":
+          description: "Saved entry to bookmarks (201)"
+        "204":
+          description: "Saved entry to bookmarks (204)"
+        "400":
+          description: "Something was wrong with the request. Check the body for error messages."
+        "401":
+          description: "Unauthorized"
+        "403":
+          description: "Forbidden"
+        "502":
+          description: "Bad gateway"
+        "503":
+          description: "Service unavailable"
+    delete:
+      security:
+        - cookieAuthProduction: []
+        - cookieAuthStaging: []
+      operationId: deleteRpcBookmark
+      description:
+        Delete one or all bookmarks:<br>
+        <b>delete one bookmark:</b> If you want to delete one specific bookmark/UUID,<br>
+        you have to set its UUID as a parameters.<br>
+        <b>delete all bookmarks:</b> To delete all bookmarks, call this endpoint without parameters.
+      tags:
+        - bookmarks
+      parameters:
+        - in: query
+          name: uuid
+          required: false
+          schema:
+            $ref: "#/components/schemas/UUIDFilter"
+          description: UUID of an article
+      responses:
+        "204":
+          description: "Deleted entry from bookmarks or delete all bookmarks, respectively"
+        "400":
+          description: "Something was wrong with the request to delete a bookmark. Check the body for error messages."
+        "401":
+          description: "Unauthorized to delete a bookmark"
+        "403":
+          description: "Forbidden from deleting a bookmark"
+        "502":
+          description: "Bad gateway to delete a bookmark"
+        "503":
+          description: "Service unavailable for deleting bookmarks"
+
+  /merkl/categories:
+    get:
+      security:
+        - cookieAuthProduction: []
+        - cookieAuthStaging: []
+      summary: "Returns the bookmark categories"
+      tags:
+        - categories
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    ssoid:
+                      type: integer
+                      example: 54
+                    uuid:
+                      $ref: "#/components/schemas/UUID"
+          description: "Success getting categories"
+        "400":
+          description: "Something was wrong with the request to get categories. Check the body for error messages."
+        "401":
+          description: "Unauthorized to get categories"
+        "503":
+          description: "Service unavailable for getting categories"
+
   /bookmarks:
     get:
       security:
@@ -57,7 +221,7 @@ paths:
               type: object
               properties:
                 id:
-                  $ref:   "#/components/schemas/UUID"
+                  $ref: "#/components/schemas/UUID"
       responses:
         "201":
           description: "Saved entry to bookmarks"
@@ -542,6 +706,34 @@ components:
       items:
         $ref: "#/components/schemas/UUID"
 
+    UUIDFilter:
+      type: string
+      pattern: ^[eq\.]+(([a-f0-9]{8})(-[a-f0-9]{4}){3}(-[a-f0-9]{12})\\}?|[-a-z0-9/]+)$
+      description: Postgrest equal filter function
+      example: "eq.d995ba5a-a7fb-401a-bdc8-86cf2cbf0cda"
+
+    Bookmark:
+      type: array
+      description: Describes a bookmark item
+      items:
+        type: object
+        properties:
+          created:
+            type: string
+            example: "2022-11-25T16:18:37.124812+00:00"
+          ssoid:
+            type: integer
+            example: 42
+          uuid:
+            $ref: "#/components/schemas/UUID"
+
+    Category:
+      description: Describes a filtered list of UUIDs
+      type: array
+      items:
+        type: string
+        example: "d995ba5a-a7fb-401a-bdc8-86cf2cbf0cda"
+
     BookmarkIds:
       type: object
       items: